Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/openapi-tools/swagger-maven-plugin
Maven plugin to activate the Swagger Core library to generate OpenAPI documentation.
https://github.com/openapi-tools/swagger-maven-plugin
api-documentation api-documentation-tool api-rest easy-openapi-specification openapi openapi-component openapi-maven-plugin openapi-specification openapi-tools swagger-api swagger-maven-plugin
Last synced: 2 days ago
JSON representation
Maven plugin to activate the Swagger Core library to generate OpenAPI documentation.
- Host: GitHub
- URL: https://github.com/openapi-tools/swagger-maven-plugin
- Owner: openapi-tools
- License: mit
- Created: 2017-09-05T15:03:06.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-07-27T11:30:21.000Z (6 months ago)
- Last Synced: 2025-01-04T22:12:21.340Z (9 days ago)
- Topics: api-documentation, api-documentation-tool, api-rest, easy-openapi-specification, openapi, openapi-component, openapi-maven-plugin, openapi-specification, openapi-tools, swagger-api, swagger-maven-plugin
- Language: Java
- Homepage:
- Size: 128 KB
- Stars: 73
- Watchers: 10
- Forks: 45
- Open Issues: 58
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Swagger Maven Plugin
This plugin is intended to use the [Swagger Core library](https://github.com/swagger-api/swagger-core) to generate
OpenAPI documentation from a JAX-RS based REST service with as little change as possible. This allows for @SwaggerDefinition, @ReaderListener and ModelConverters to work the same way as with the core Swagger library.
# Status
The plugin is considered production ready. The version 2.x.x of the plugin is supporting generation of OpenAPI version 3 specifications using Swagger 2.x. To generate OpenAPI version 2 specifications using Swagger 1.x use the latest 1.x.x version of the plugin.
[](https://maven-badges.herokuapp.com/maven-central/io.openapitools.swagger/swagger-maven-plugin/)
[](https://www.javadoc.io/doc/io.openapitools.swagger/swagger-maven-plugin)
[](https://travis-ci.org/openapi-tools/swagger-maven-plugin)
[](https://snyk.io/test/github/openapi-tools/swagger-maven-plugin)
# Usage
To have Swagger generate the OpenAPI specifications as part of the build add in the plugin to the POM.
```xml
...
io.openapitools.swagger
swagger-maven-plugin
io.openapitools.swagger.example
io.openapitools.swagger.example.alternate
${basedir}/target/
swagger
JSON,YAML
true
generate
...
```
This will run the generation in the prepare-package lifecycle stage of the Maven build.
## Specifying Packages with JAX-RS Endpoints
The packages containing JAX-RS endpoints must be configured using the resourcePackages element. See the minimal configuration above.
## Properties of Swagger model
Most general properties of the Swagger model is configurable using the swaggerConfig element. Note this may also be configured through the @OpenAPIDefinition annotation - see [Customizing your auto-generated Swagger Definitions](http://swagger.io/customizing-your-auto-generated-swagger-definitions-in-1-5-x/).
```xml
io.openapitools.swagger
swagger-maven-plugin
https://services.exmple.it/base/path
Endpoint URL
Title
1.0.0
Terms
[email protected]
My Name
https://google.com
https://license
MIT
my-custom-field-1
my-custom-field-2
src/test/resources/descriptions.md
```
## Deploying
The generated OpenAPI specifications may be installed and deployed as Maven artifact. To enable this add the configuration parameter attachSwaggerArtifact.
```xml
io.openapitools.swagger
swagger-maven-plugin
true
```
# Acknowledgement
Thanks to [Yukai Kong](https://github.com/kongchen) for his work on
[Swagger Maven plugin](https://github.com/kongchen/swagger-maven-plugin). This plugin is heavily inspired by that.