## File: README.md # Swagger Core **NOTE:** If you're looking for Swagger Core 1.5.X and OpenAPI 2.0, please refer to [1.5 branch](https://github.com/swagger-api/swagger-core/tree/1.5). **NOTE:** Since version 2.1.7, Swagger Core also supports the Jakarta namespace. There are a parallel set of artifacts with the `-jakarta` suffix, providing the same functionality as the unsuffixed (i.e.: `javax`) artifacts. Please see the [Wiki](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Getting-started) for more details. **NOTE:** Since version 2.2.0 Swagger Core supports OpenAPI 3.1; see [this page](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---OpenAPI-3.1) for details [](https://maven-badges.herokuapp.com/maven-central/io.swagger.core.v3/swagger-project) Swagger Core is a Java implementation of the OpenAPI Specification. Current version supports *JAX-RS2* (`javax` and `jakarta` namespaces). ## Get started with Swagger Core! See the guide on [getting started with Swagger Core](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Getting-started) to get started with adding Swagger to your API. ## See the Wiki! The [github wiki](https://github.com/swagger-api/swagger-core/wiki) contains documentation, samples, contributions, etc. Start there. ## Compatibility The OpenAPI Specification has undergone several revisions since initial creation in 2010. The Swagger Core project has the following compatibilities with the OpenAPI Specification: Swagger core Version | Release Date | OpenAPI Spec compatibility | Notes | Status ------------------------- | ------------ | -------------------------- | ----- | ---- 2.2.54 (**current stable**)| 2026-08-18 | 3.x | [tag v2.2.54](https://github.com/swagger-api/swagger-core/tree/v2.2.54) | Supported 2.2.53 | 2026-08-03 | 3.x | [tag v2.2.53](https://github.com/swagger-api/swagger-core/tree/v2.2.53) | Supported 2.2.52 | 2026-06-22 | 3.x | [tag v2.2.52](https://github.com/swagger-api/swagger-core/tree/v2.2.52) | Supported 2.2.51 | 2026-06-12 | 3.x | [tag v2.2.51](https://github.com/swagger-api/swagger-core/tree/v2.2.51) | Supported 2.2.50 | 2026-05-12 | 3.x | [tag v2.2.50](https://github.com/swagger-api/swagger-core/tree/v2.2.50) | Supported 2.2.49 | 2026-04-28 | 3.x | [tag v2.2.49](https://github.com/swagger-api/swagger-core/tree/v2.2.49) | Supported 2.2.48 | 2026-04-13 | 3.x | [tag v2.2.48](https://github.com/swagger-api/swagger-core/tree/v2.2.48) | Supported 2.2.47 | 2026-04-09 | 3.x | [tag v2.2.47](https://github.com/swagger-api/swagger-core/tree/v2.2.47) | Supported 2.2.46 | 2026-03-31 | 3.x | [tag v2.2.46](https://github.com/swagger-api/swagger-core/tree/v2.2.46) | Supported 2.2.45 | 2026-03-09 | 3.x | [tag v2.2.45](https://github.com/swagger-api/swagger-core/tree/v2.2.45) | Supported 2.2.44 | 2026-03-03 | 3.x | [tag v2.2.44](https://github.com/swagger-api/swagger-core/tree/v2.2.44) | Supported 2.2.43 | 2026-02-17 | 3.x | [tag v2.2.43](https://github.com/swagger-api/swagger-core/tree/v2.2.43) | Supported 2.2.42 | 2026-01-19 | 3.x | [tag v2.2.42](https://github.com/swagger-api/swagger-core/tree/v2.2.42) | Supported 2.2.41 | 2025-11-24 | 3.x | [tag v2.2.41](https://github.com/swagger-api/swagger-core/tree/v2.2.41) | Supported 2.2.40 | 2025-10-28 | 3.x | [tag v2.2.40](https://github.com/swagger-api/swagger-core/tree/v2.2.40) | Supported 2.2.39 | 2025-10-13 | 3.x | [tag v2.2.39](https://github.com/swagger-api/swagger-core/tree/v2.2.39) | Supported 2.2.38 | 2025-09-29 | 3.x | [tag v2.2.38](https://github.com/swagger-api/swagger-core/tree/v2.2.38) | Supported 2.2.37 | 2025-09-16 | 3.x | [tag v2.2.37](https://github.com/swagger-api/swagger-core/tree/v2.2.37) | Supported 2.2.36 | 2025-08-18 | 3.x | [tag v2.2.36](https://github.com/swagger-api/swagger-core/tree/v2.2.36) | Supported 2.2.35 | 2025-07-31 | 3.x | [tag v2.2.35](https://github.com/swagger-api/swagger-core/tree/v2.2.35) | Supported 2.2.34 | 2025-06-20 | 3.x | [tag v2.2.34](https://github.com/swagger-api/swagger-core/tree/v2.2.34) | Supported 2.2.33 | 2025-06-12 | 3.x | [tag v2.2.33](https://github.com/swagger-api/swagger-core/tree/v2.2.33) | Supported 2.2.32 | 2025-05-14 | 3.x | [tag v2.2.32](https://github.com/swagger-api/swagger-core/tree/v2.2.32) | Supported 2.2.31 | 2025-05-13 | 3.x | [tag v2.2.31](https://github.com/swagger-api/swagger-core/tree/v2.2.31) | Supported 2.2.30 | 2025-04-07 | 3.x | [tag v2.2.30](https://github.com/swagger-api/swagger-core/tree/v2.2.30) | Supported 2.2.29 | 2025-03-10 | 3.x | [tag v2.2.29](https://github.com/swagger-api/swagger-core/tree/v2.2.29) | Supported 2.2.28 | 2025-01-16 | 3.x | [tag v2.2.28](https://github.com/swagger-api/swagger-core/tree/v2.2.28) | Supported 2.2.27 | 2024-12-11 | 3.x | [tag v2.2.27](https://github.com/swagger-api/swagger-core/tree/v2.2.27) | Supported 2.2.26 | 2024-11-18 | 3.x | [tag v2.2.26](https://github.com/swagger-api/swagger-core/tree/v2.2.26) | Supported 2.2.25 | 2024-10-02 | 3.x | [tag v2.2.25](https://github.com/swagger-api/swagger-core/tree/v2.2.25) | Supported 2.2.24 | 2024-09-23 | 3.x | [tag v2.2.24](https://github.com/swagger-api/swagger-core/tree/v2.2.24) | Supported 2.2.23 | 2024-08-28 | 3.x | [tag v2.2.23](https://github.com/swagger-api/swagger-core/tree/v2.2.23) | Supported 2.2.22 | 2024-05-15 | 3.x | [tag v2.2.22](https://github.com/swagger-api/swagger-core/tree/v2.2.22) | Supported 2.2.21 | 2024-03-20 | 3.x | [tag v2.2.21](https://github.com/swagger-api/swagger-core/tree/v2.2.21) | Supported 2.2.20 | 2023-12-19 | 3.x | [tag v2.2.20](https://github.com/swagger-api/swagger-core/tree/v2.2.20) | Supported 2.2.19 | 2023-11-10 | 3.x | [tag v2.2.19](https://github.com/swagger-api/swagger-core/tree/v2.2.19) | Supported 2.2.18 | 2023-10-25 | 3.x | [tag v2.2.18](https://github.com/swagger-api/swagger-core/tree/v2.2.18) | Supported 2.2.17 | 2023-10-12 | 3.x | [tag v2.2.17](https://github.com/swagger-api/swagger-core/tree/v2.2.17) | Supported 2.2.16 | 2023-09-18 | 3.x | [tag v2.2.16](https://github.com/swagger-api/swagger-core/tree/v2.2.16) | Supported 2.2.15 | 2023-07-08 | 3.x | [tag v2.2.15](https://github.com/swagger-api/swagger-core/tree/v2.2.15) | Supported 2.2.14 | 2023-06-26 | 3.x | [tag v2.2.14](https://github.com/swagger-api/swagger-core/tree/v2.2.14) | Supported 2.2.13 | 2023-06-24 | 3.x | [tag v2.2.13](https://github.com/swagger-api/swagger-core/tree/v2.2.13) | Supported 2.2.12 | 2023-06-13 | 3.x | [tag v2.2.12](https://github.com/swagger-api/swagger-core/tree/v2.2.12) | Supported 2.2.11 | 2023-06-01 | 3.x | [tag v2.2.11](https://github.com/swagger-api/swagger-core/tree/v2.2.11) | Supported 2.2.10 | 2023-05-15 | 3.x | [tag v2.2.10](https://github.com/swagger-api/swagger-core/tree/v2.2.10) | Supported 2.2.9 | 2023-03-20 | 3.x | [tag v2.2.9](https://github.com/swagger-api/swagger-core/tree/v2.2.9) | Supported 2.2.8 | 2023-01-06 | 3.x | [tag v2.2.8](https://github.com/swagger-api/swagger-core/tree/v2.2.8) | Supported 2.2.7 | 2022-11-15 | 3.0 | [tag v2.2.7](https://github.com/swagger-api/swagger-core/tree/v2.2.7) | Supported 2.2.6 | 2022-11-02 | 3.0 | [tag v2.2.6](https://github.com/swagger-api/swagger-core/tree/v2.2.6) | Supported 2.2.5 | 2022-11-02 | 3.0 | [tag v2.2.5](https://github.com/swagger-api/swagger-core/tree/v2.2.5) | Supported 2.2.4 | 2022-10-16 | 3.0 | [tag v2.2.4](https://github.com/swagger-api/swagger-core/tree/v2.2.4) | Supported 2.2.3 | 2022-09-27 | 3.0 | [tag v2.2.3](https://github.com/swagger-api/swagger-core/tree/v2.2.3) | Supported 2.2.2 | 2022-07-20 | 3.0 | [tag v2.2.2](https://github.com/swagger-api/swagger-core/tree/v2.2.2) | Supported 2.2.1 | 2022-06-15 | 3.0 | [tag v2.2.1](https://github.com/swagger-api/swagger-core/tree/v2.2.1) | Supported 2.2.0 | 2022-04-04 | 3.0 | [tag v2.2.0](https://github.com/swagger-api/swagger-core/tree/v2.2.0) | Supported 2.1.13 | 2022-02-07 | 3.0 | [tag v2.1.13](https://github.com/swagger-api/swagger-core/tree/v2.1.13) | Supported 2.1.12 | 2021-12-23 | 3.0 | [tag v2.1.12](https://github.com/swagger-api/swagger-core/tree/v2.1.12) | Supported 2.1.11 | 2021-09-29 | 3.0 | [tag v2.1.11](https://github.com/swagger-api/swagger-core/tree/v2.1.11) | Supported 2.1.10 | 2021-06-28 | 3.0 | [tag v2.1.10](https://github.com/swagger-api/swagger-core/tree/v2.1.10) | Supported 2.1.9 | 2021-04-20 | 3.0 | [tag v2.1.9](https://github.com/swagger-api/swagger-core/tree/v2.1.9) | Supported 2.1.8 | 2021-04-18 | 3.0 | [tag v2.1.8](https://github.com/swagger-api/swagger-core/tree/v2.1.8) | Supported 2.1.7 | 2021-02-18 | 3.0 | [tag v2.1.7](https://github.com/swagger-api/swagger-core/tree/v2.1.7) | Supported 2.1.6 | 2020-12-04 | 3.0 | [tag v2.1.6](https://github.com/swagger-api/swagger-core/tree/v2.1.6) | Supported 2.1.5 | 2020-10-01 | 3.0 | [tag v2.1.5](https://github.com/swagger-api/swagger-core/tree/v2.1.5) | Supported 2.1.4 | 2020-07-24 | 3.0 | [tag v2.1.4](https://github.com/swagger-api/swagger-core/tree/v2.1.4) | Supported 2.1.3 | 2020-06-27 | 3.0 | [tag v2.1.3](https://github.com/swagger-api/swagger-core/tree/v2.1.3) | Supported 2.1.2 | 2020-04-01 | 3.0 | [tag v2.1.2](https://github.com/swagger-api/swagger-core/tree/v2.1.2) | Supported 2.1.1 | 2020-01-02 | 3.0 | [tag v2.1.1](https://github.com/swagger-api/swagger-core/tree/v2.1.1) | Supported 2.1.0 | 2019-11-16 | 3.0 | [tag v2.1.0](https://github.com/swagger-api/swagger-core/tree/v2.1.0) | Supported 2.0.10 | 2019-10-11 | 3.0 | [tag v2.0.10](https://github.com/swagger-api/swagger-core/tree/v2.0.10) | Supported 2.0.9 | 2019-08-22 | 3.0 | [tag v2.0.9](https://github.com/swagger-api/swagger-core/tree/v2.0.9) | Supported 2.0.8 | 2019-04-24 | 3.0 | [tag v2.0.8](https://github.com/swagger-api/swagger-core/tree/v2.0.8) | Supported 2.0.7 | 2019-02-18 | 3.0 | [tag v2.0.7](https://github.com/swagger-api/swagger-core/tree/v2.0.7) | Supported 2.0.6 | 2018-11-27 | 3.0 | [tag v2.0.6](https://github.com/swagger-api/swagger-core/tree/v2.0.6) | Supported 2.0.5 | 2018-09-19 | 3.0 | [tag v2.0.5](https://github.com/swagger-api/swagger-core/tree/v2.0.5) | Supported 2.0.4 | 2018-09-05 | 3.0 | [tag v2.0.4](https://github.com/swagger-api/swagger-core/tree/v2.0.4) | Supported 2.0.3 | 2018-08-09 | 3.0 | [tag v2.0.3](https://github.com/swagger-api/swagger-core/tree/v2.0.3) | Supported 1.6.14 (**current stable**)| 2024-03-19 | 2.0 | [tag v1.6.14](https://github.com/swagger-api/swagger-core/tree/v1.6.14) | Supported 1.6.13 | 2024-01-26 | 2.0 | [tag v1.6.13](https://github.com/swagger-api/swagger-core/tree/v1.6.13) | Supported 1.6.12 | 2023-10-14 | 2.0 | [tag v1.6.12](https://github.com/swagger-api/swagger-core/tree/v1.6.12) | Supported 1.6.11 | 2023-05-15 | 2.0 | [tag v1.6.11](https://github.com/swagger-api/swagger-core/tree/v1.6.11) | Supported 1.6.10 | 2023-03-21 | 2.0 | [tag v1.6.10](https://github.com/swagger-api/swagger-core/tree/v1.6.10) | Supported 1.6.9 | 2022-11-15 | 2.0 | [tag v1.6.9](https://github.com/swagger-api/swagger-core/tree/v1.6.9) | Supported 1.6.8 | 2022-10-16 | 2.0 | [tag v1.6.8](https://github.com/swagger-api/swagger-core/tree/v1.6.8) | Supported 1.6.7 | 2022-09-27 | 2.0 | [tag v1.6.7](https://github.com/swagger-api/swagger-core/tree/v1.6.7) | Supported 1.6.6 | 2022-04-04 | 2.0 | [tag v1.6.6](https://github.com/swagger-api/swagger-core/tree/v1.6.6) | Supported 1.6.5 | 2022-02-07 | 2.0 | [tag v1.6.5](https://github.com/swagger-api/swagger-core/tree/v1.6.5) | Supported 1.6.4 | 2021-12-23 | 2.0 | [tag v1.6.4](https://github.com/swagger-api/swagger-core/tree/v1.6.4) | Supported 1.6.3 | 2021-09-29 | 2.0 | [tag v1.6.3](https://github.com/swagger-api/swagger-core/tree/v1.6.3) | Supported 1.6.2 | 2020-07-01 | 2.0 | [tag v1.6.2](https://github.com/swagger-api/swagger-core/tree/v1.6.2) | Supported 1.6.1 | 2020-04-01 | 2.0 | [tag v1.6.1](https://github.com/swagger-api/swagger-core/tree/v1.6.1) | Supported 1.6.0 | 2019-11-16 | 2.0 | [tag v1.6.0](https://github.com/swagger-api/swagger-core/tree/v1.6.0) | Supported 1.5.24 | 2019-10-11 | 2.0 | [tag v1.5.24](https://github.com/swagger-api/swagger-core/tree/v1.5.24) | Supported 1.5.23 | 2019-08-22 | 2.0 | [tag v1.5.23](https://github.com/swagger-api/swagger-core/tree/v1.5.23) | Supported 1.5.22 | 2019-02-18 | 2.0 | [tag v1.5.22](https://github.com/swagger-api/swagger-core/tree/v1.5.22) | Supported 1.5.21 | 2018-08-09 | 2.0 | [tag v1.5.21](https://github.com/swagger-api/swagger-core/tree/v1.5.21) | Supported 1.5.20 | 2018-05-23 | 2.0 | [tag v1.5.20](https://github.com/swagger-api/swagger-core/tree/v1.5.20) | Supported 2.0.2 | 2018-05-23 | 3.0 | [tag v2.0.2](https://github.com/swagger-api/swagger-core/tree/v2.0.2) | Supported 2.0.1 | 2018-04-16 | 3.0 | [tag v2.0.1](https://github.com/swagger-api/swagger-core/tree/v2.0.1) | Supported 1.5.19 | 2018-04-16 | 2.0 | [tag v1.5.19](https://github.com/swagger-api/swagger-core/tree/v1.5.19) | Supported 2.0.0 | 2018-03-20 | 3.0 | [tag v2.0.0](https://github.com/swagger-api/swagger-core/tree/v2.0.0) | Supported 2.0.0-rc4 | 2018-01-22 | 3.0 | [tag v2.0.0-rc4](https://github.com/swagger-api/swagger-core/tree/v2.0.0-rc4) | Supported 2.0.0-rc3 | 2017-11-21 | 3.0 | [tag v2.0.0-rc3](https://github.com/swagger-api/swagger-core/tree/v2.0.0-rc3) | Supported 2.0.0-rc2 | 2017-09-29 | 3.0 | [tag v2.0.0-rc2](https://github.com/swagger-api/swagger-core/tree/v2.0.0-rc2) | Supported 2.0.0-rc1 | 2017-08-17 | 3.0 | [tag v2.0.0-rc1](https://github.com/swagger-api/swagger-core/tree/v2.0.0-rc1) | Supported 1.5.18 | 2018-01-22 | 2.0 | [tag v1.5.18](https://github.com/swagger-api/swagger-core/tree/v1.5.18) | Supported 1.5.17 | 2017-11-21 | 2.0 | [tag v1.5.17](https://github.com/swagger-api/swagger-core/tree/v1.5.17) | Supported 1.5.16 | 2017-07-15 | 2.0 | [tag v1.5.16](https://github.com/swagger-api/swagger-core/tree/v1.5.16) | Supported 1.3.12 | 2014-12-23 | 1.2 | [tag v1.3.12](https://github.com/swagger-api/swagger-core/tree/v1.3.12) | Supported 1.2.4 | 2013-06-19 | 1.1 | [tag swagger-project_2.10.0-1.2.4](https://github.com/swagger-api/swagger-core/tree/swagger-project_2.10.0-1.2.4) | Deprecated 1.0.0 | 2011-10-16 | 1.0 | [tag v1.0](https://github.com/swagger-api/swagger-core/tree/v1.0) | Deprecated ### Change History If you're interested in the change history of swagger and the Swagger Core framework, see [here](https://github.com/swagger-api/swagger-core/releases). Starting with version 2.3.0, notable changes and fixes are also documented in [CHANGELOG.md](CHANGELOG.md). ### Prerequisites You need the following installed and available in your $PATH: * Java 11 * Apache maven 3.0.4 or greater * Jackson 2.4.5 or greater ### To build from source (currently 2.2.55-SNAPSHOT) ``` # first time building locally mvn -N ``` Subsequent builds: ``` mvn install ``` This will build the modules. Of course if you don't want to build locally you can grab artifacts from maven central: `https://repo1.maven.org/maven2/io/swagger/core/` ### Maven BOM The `swagger-bom` artifact is a Bill of Materials that manages **both** the `javax` and Jakarta (`-jakarta` suffix) artifact families. Import it once and omit versions on all individual Swagger dependencies. > **Note:** Maven and Gradle build plugins (`swagger-maven-plugin`, `swagger-gradle-plugin`, > `swagger-eclipse-transformer-maven-plugin`) are intentionally **excluded** from the BOM. > Plugins are applied via `` or `plugins {}`, not via ``, > so including them in the BOM would be misleading and could conflict with the plugin > management section of a consumer's build. #### Maven ``` /* Detailed source-code truncated for AI context efficiency. */ ``` #### Gradle ```kotlin dependencies { implementation(platform("io.swagger.core.v3:swagger-bom:${swaggerOpenapiv3Version}")) // javax artifacts — no version needed implementation("io.swagger.core.v3:swagger-annotations") implementation("io.swagger.core.v3:swagger-core") // Jakarta namespace artifacts — no version needed implementation("io.swagger.core.v3:swagger-annotations-jakarta") implementation("io.swagger.core.v3:swagger-core-jakarta") } ``` ## Sample Apps The samples have moved to [a new repository](https://github.com/swagger-api/swagger-samples/tree/2.0) and contain various integrations and configurations. ## Security contact Please disclose any security-related issues or vulnerabilities by emailing [security@swagger.io](mailto:security@swagger.io), instead of using the public issue tracker. --- ## File: modules/swagger-project-jakarta/modules/swagger-maven-plugin-jakarta/transformed/README.md #### Don't delete Target directory for eclipse transformer plugin; Jakarta EE 9+ artifacts are generated in this directory --- ## File: modules/swagger-maven-plugin/README.md # swagger-maven-plugin * Resolves project openAPI specification and saves the result in JSON, YAML or both formats. All parameters except `outputFileName`, `outputFormat`, `skip`, `encoding` and `outputPath` correspond to `swagger` [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties) with same name. ## Jakarta namespace support Since version 2.1.7 Swagger Core supports also Jakarta namespace, with a parallel set of artifacts with `-jakarta` suffix, providing the same functionality as the "standard" `javax` namespace ones. Please check [Wiki](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Getting-started) for more details Both `javax` and `jakarta` examples are provided below ## Configuration example ### `javax` namespace ```xml io.swagger.core.v3 swagger-maven-plugin 2.2.54 openapi ${project.build.directory}/generatedtest JSONANDYAML test.petstore TRUE compile resolve io.swagger.core.v3 swagger-jaxrs2 2.2.54 javax.ws.rs javax.ws.rs-api 2.1 javax.servlet javax.servlet-api 3.1.0 ``` ### `jakarta` namespace ```xml io.swagger.core.v3 swagger-maven-plugin-jakarta 2.2.54 openapi ${project.build.directory}/generatedtest JSONANDYAML test.petstore TRUE compile resolve io.swagger.core.v3 swagger-jaxrs2-jakarta 2.2.54 jakarta.ws.rs jakarta.ws.rs-api 3.0.0 jakarta.servlet jakarta.servlet-api 5.0.0 ``` ## Configuration example with provided Swagger configuration file ### `javax` namespace ```xml io.swagger.core.v3 swagger-maven-plugin 2.2.54 openapi ${project.build.directory}/generatedtest ${project.basedir}/src/main/resources/configurationFile.yaml compile resolve ... ``` ### `jakarta` namespace ```xml io.swagger.core.v3 swagger-maven-plugin-jakarta 2.2.54 openapi ${project.build.directory}/generatedtest ${project.basedir}/src/main/resources/configurationFile.yaml compile resolve ... ``` #### Parameters Parameter | Description | Required | Default --------- | ----------- |---------------| ------- `outputPath`|output path where file(s) are saved| true | `outputFileName`|file name (no extension)| false |`openapi` `outputFormat`|file format (`JSON`, `YAML`, `JSONANDYAML`| false |`JSON` `skip`|if `TRUE` skip execution| false |`FALSE` `encoding`|encoding of output file(s)| false | `resourcePackages`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| false | `resourceClasses`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| false | `prettyPrint`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| false |`TRUE` `sortOutput`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| false |`FALSE` `alwaysResolveAppPath`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| false |`FALSE` `skipResolveAppPath`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| false |`FALSE` `openapiFilePath`|path to openapi file to be merged with resolved specification, see [config](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| false | `configurationFilePath`|path to swagger config file to be merged with resolved specification, see [config](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration)| false | `filterClass`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| false | `readerClass`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| false | `scannerClass`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| false | `readAllResources`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| false | `ignoredRoutes`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| false | `objectMapperProcessorClass`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| false | `defaultResponseCode`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| false | `groupsValidationStrategy`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false| `validatorProcessorClass`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false| `modelConverterClasses`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| false | `contextId`|see [Context](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#context)| false |${project.artifactId} `openapi31`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| false | `schemaResolution`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| DEFAULT | `openAPIVersion`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| `3.0.1/3.1.0` | *** Since version 2.0.8, `configurationFilePath` parameter is available, allowing to specify a path to a [swagger configuration file](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration); If single maven configuration parameters (e.g. `prettyPrint`) are also defined, these will overwrite any value set in configuration file; the same applies to `openapiFilePath` which takes precedence over `openAPI` field in configuration file. Since version 2.1.6, `sortOutput` parameter is available, allowing to sort object properties and map keys alphabetically. Since version 2.1.6, `objectMapperProcessorClass` allows to configure also the ObjectMapper instance used to serialize the resolved OpenAPI Since version 2.1.9, `alwaysResolveAppPath` parameter is available, allowing to trigger resolving of Application Path from annotation also not in runtime (e.g. using servlet in separate application, or in maven plugin at build time, etc) Since version 2.2.12, `openapi31` parameter is available, if set to true the resolved spec will be processed into a 3.1.0 specification by resolving according to OAS 3.1 rules Since version 2.1.15, `skipResolveAppPath` parameter is available, allowing to skip resolving of Application Path from annotation Since version 2.2.17, `defaultResponseCode` parameter is available, allowing to set the code used when resolving responses with no http status code annotation Since version 2.2.24, `schemaResolution` parameter is available, allowing to specify how object schemas and object properties within schemas are resolved for OAS 3.0 specification Since version 2.2.28, `openAPIVersion` parameter is available, allowing to specify the version of the OpenAPI specification to be used for the resolved spec. Since version 2.2.29, `groupsValidationStrategy` parameter is available, allowing to specify the strategy for resolving Validation annotations (`never`, `always`, `neverIfNoContext`). Since version 2.2.29, `validatorProcessorClass` parameter is available, allowing to specify a custom validator processor class, implementation of `io.swagger.v3.core.util.ValidatorProcessor`. --- ## File: modules/swagger-gradle-plugin/README.md # swagger-gradle-plugin **`swagger-gradle-plugin` supports gradle 3.2 and higher.** ## Jakarta namespace support Since version 2.1.7 Swagger Core supports also Jakarta namespace, with a parallel set of artifacts with `-jakarta` suffix, providing the same functionality as the "standard" `javax` namespace ones. Please check [Wiki](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Getting-started) for more details To have gradle plugin use the `jakarta` namespace artifacts, you need to provide a value to parameter `buildClasspath` In many cases it is sufficient to set it to the `classpath` value, like: `buildClasspath = classpath` Alternatively provide as value a classpath with the following dependencies (replacing the provided [`javax` ones](https://github.com/swagger-api/swagger-core/blob/master/modules/swagger-gradle-plugin/src/main/java/io/swagger/v3/plugins/gradle/SwaggerPlugin.java#L16-L25)): * org.apache.commons:commons-lang3:3.20.0 * io.swagger.core.v3:swagger-jaxrs2-jakarta:2.2.9 * jakarta.ws.rs:jakarta.ws.rs-api:3.0.0 * jakarta.servlet:jakarta.servlet-api:5.0.0 ## Installation ### Gradle 3.2 and higher ``` plugins { id "io.swagger.core.v3.swagger-gradle-plugin" version "2.2.54" } ``` ### Gradle 1.x and 2.0 **NOTE**: Since version `2.0.10` gradle 1.x and 2.x up to 3.1 are not supported. with versions up to `2.0.9`: ``` buildscript { repositories { maven { url "https://plugins.gradle.org/m2/" } } dependencies { classpath "io.swagger.core.v3:swagger-gradle-plugin:2.2.54" } } apply plugin: "io.swagger.core.v3.swagger-gradle-plugin" ``` ## Tasks ### resolve * Resolves project openAPI specification and saves the result in JSON, YAML or both formats. All parameters except `outputFileName`, `outputFormat`, `classpath`, `skip`, `encoding`, `outputDir` and `outputPath` correspond to `swagger` [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties) with same name. #### Example Usage ``` resolve { outputFileName = 'PetStoreAPI' outputFormat = 'JSON' prettyPrint = 'TRUE' classpath = sourceSets.main.runtimeClasspath resourcePackages = ['io.test'] outputDir = file('test') } ``` #### Parameters Parameter | Description | Required | Default --------- | ----------- | --------- | ------- `classpath`|classpath for resources to scan (swagger and deps already included in classpath)|true| `outputDir`|output path where file(s) are saved|true| `outputFileName`|file name (no extension)|false|`openapi` `outputFormat`|file format (`JSON`, `YAML`, `JSONANDYAML`|false|`JSON` `skip`|if `TRUE` skip execution|false|`FALSE` `encoding`|encoding of output file(s)|false| `resourcePackages`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false| `resourceClasses`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false| `prettyPrint`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false|`TRUE` `sortOutput`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false|`FALSE` `alwaysResolveAppPath`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false|`FALSE` `skipResolveAppPath`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false|`FALSE` `openApiFile`|openapi file to be merged with resolved specification, equivalent to [config](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties) openAPI|false| `filterClass`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false| `readerClass`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false| `scannerClass`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false| `readAllResources`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false| `ignoredRoutes`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false| `objectMapperProcessorClass`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false| `modelConverterClasses`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false| `contextId`|see [Context](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#context)|false| `outputPath`|**DEPRECATED** output path where file(s) are saved|false| `defaultResponseCode`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false| `groupsValidationStrategy`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false| `validatorProcessorClass`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false| `openapi31`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| false | `schemaResolution`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| DEFAULT | `openAPIVersion`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)| `3.0.1/3.1.0` | **Note** parameter `openApiFile` corresponds to [config](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties) openAPI. It points to a location of a file in YAML or JSON format representing the input spec that will be merged with the resolved spec. Typically used to add Info section, or any other meta data. An example of such file: ```yaml openapi: 3.0.4 info: version: '1.0' title: Swagger Pet Sample App Config File about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key special-key to test the authorization filters.' termsOfService: http://swagger.io/terms/ contact: email: apiteam@swagger.io license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html ``` - Since version 2.1.6, `sortOutput` parameter is available, allowing to sort object properties and map keys alphabetically. - Since version 2.1.6, `objectMapperProcessorClass` allows to configure also the ObjectMapper instance used to serialize the resolved OpenAPI - Since version 2.1.9, `alwaysResolveAppPath` parameter is available, allowing to trigger resolving of Application Path from annotation also not in runtime (e.g. using servlet in separate application, or in maven plugin at build time, etc) - Since version 2.2.12, `openapi31` parameter is available, if set to true the resolved spec will be processed into a 3.1.0 specification by resolving according to OAS 3.1 rules - Since version 2.1.15, `skipResolveAppPath` parameter is available, allowing to skip resolving of Application Path from annotation - Since version 2.2.17, `defaultResponseCode` parameter is available, allowing to set the code used when resolving responses with no http status code annotation - Since version 2.2.24, `schemaResolution` parameter is available, allowing to specify how object schemas and object properties within schemas are resolved for OAS 3.0 specification - Since version 2.2.28, `openAPIVersion` parameter is available, allowing to specify the version of the OpenAPI specification to be used for the resolved spec. - Since version 2.2.29, `groupsValidationStrategy` parameter is available, allowing to specify the strategy for resolving Validation annotations (`never`, `always`, `neverIfNoContext`). - Since version 2.2.29, `validatorProcessorClass` parameter is available, allowing to specify a custom validator processor class, implementation of `io.swagger.v3.core.util.ValidatorProcessor`. --- ## File: modules/swagger-eclipse-transformer-maven-plugin/README.md Adapted from https://github.com/eclipse/transformer/blob/main/org.eclipse.transformer.maven not to add the transformed JAR as an attached artifact to the project. To be replaced with Eclipse original Transformer plugin when/if optional attachment is supported.