https://github.com/openapi-tools/api-pp-maven-plugin
Maven module for Post Processing Open API specifications making service evolution easier
https://github.com/openapi-tools/api-pp-maven-plugin
Last synced: 11 months ago
JSON representation
Maven module for Post Processing Open API specifications making service evolution easier
- Host: GitHub
- URL: https://github.com/openapi-tools/api-pp-maven-plugin
- Owner: openapi-tools
- License: mit
- Created: 2018-02-04T12:47:30.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2018-12-01T17:25:58.000Z (about 7 years ago)
- Last Synced: 2025-01-25T12:07:02.933Z (about 1 year ago)
- Language: Java
- Homepage:
- Size: 25.4 KB
- Stars: 0
- Watchers: 4
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# API Post Processing Maven Plugin
The long story short: this module avoids annotation clutter in your code and gives you the ability to process your Open API specification
in your continous build or pipeline before piublishing your Open API specification.
The plugin allows you to include resposes like 301 to allow for future changes to resources and e.g. 202 for
deferred processing and so on.
## Status
This plugin is intended to use the [Swagger Core library](https://github.com/swagger-api/swagger-core) to extend
OpenAPI specification with request and reponse headers, reponse codes etc. in order for a build pipeline to extend
REST services with defaults.
[](https://travis-ci.org/openapi-tools/api-pp-maven-plugin)
Module is ready as an initial version
# Where to apply
The idea is to minimize the annotation clutter in the code and postpone what you would always and automate that as a part of development.
Thus this could be used during continous integration or as a step in the continous delivery pipeline
- e.g. as a step for making the Open API specification ready for consumers and having added the necessary items to the specification,
which makes it possible for the API to evolve whilst keeping consumers happy. The optimal situation is obtained if the content versioning
paradigm (having support for multiple versions in same endpoint) is used.
# Future
The initial version supports a rudimentary standard and mininmal collection of reponse and request codes and headers.
The module will be extended with a more fine grained support for individual request headers, response status codes and headers, if this is found useful.
# Usage
To have Swagger generate the OpenAPI specifications as part of the build add in the plugin to the POM.
The standard collection of status codes and headers
```xml
...
io.openapitools.api.specification
api-pp-maven-plugin
standard
...
```
This will run the generation in the verify lifecycle stage of the Maven build.
## Specifying Packages
The packages currently supported are:
standard - adds (200, 201, 202, 203, 204, 301, 304, 307, 400, 401, 402, 403, 404, 406, 410, 412, 415, 422, 429, 500, 501, 503, 505 ....)
minimum - adds (200, 202, 204, 301, 304, 400, 415, 500)
Not supported yet:
individual - adding individual reponse codes and/or headers, but will be if enough people find it useful
### Full Configuration - Standard Post Processing
The fully populated configuration example giving the _standard_ post processing collection of the Open API.
```xml
...
io.openapitools.swagger
api-pp-maven-plugin
standard
sample-api
petstore
target/api-standard
open-api-specs-standard
JSON
YAML
...
```
### Minimum Config - Standard Post processing
The min populated configuration example giving the _standard_ post processing collection of the Open API.
```xml
...
io.openapitools.swagger
api-pp-maven-plugin
sample-api
petstore
target/open-api-minimal-config
...
```
### Full Configuration - Minimum Post Processing
The fully populated configuration example giving the _minimal_ post processing collection of the Open API.
```xml
...
io.openapitools.swagger
api-pp-maven-plugin
minimal
sample-api
petstore
target/api-min
open-api-specs-minimum
JSON
YAML
...
```
### Inidividual Codes Configuration - Post Processing
The fully populated configuration example giving the _minimal_ post processing collection of the Open API.
```xml
...
io.openapitools.swagger
api-pp-maven-plugin
200
201
202
204
301
304
400
415
500
sample-api
petstore
target/api-codes-min
open-api-specs-codes-min
JSON
YAML
...
```
## Deploying
The generated post processed OpenAPI specifications may be installed and deployed as Maven artifact.
To enable this add the configuration parameter attachArtifact.
```xml
io.openapitools.api.specification
api-pp-maven-plugin
true
```