There are a number of issues in the area of OpenAPI and Swagger. They are all gathered together on the Epic - POLICY-4123Getting issue details... STATUS .
Over time, we will move from generating the OpenAPI (Swagger) artifacts from annotations in the code to having interfaces generated from source OpenAPI artifacts, see - POLICY-4141Getting issue details... STATUS and - POLICY-4142Getting issue details... STATUS .
In the current implementation, we are using SpringFox to generate teh Swagger from the Swagger 2 annotations, but SpringFox has many bugs, is not maintained, and uses an old version of SpringBoot, preventing us from upgrading SpringBoot, see - POLICY-4142Getting issue details... STATUS . However, the SPringfox annotations are very incompatible with the new OpenAPI Java annotations. Revising the annotations would be a complex task.
Policy API and Policy PAP
The current Policy API and Policy PAP interfaces are stable. The issue here is - POLICY-4142Getting issue details... STATUS , the Swagger is generated by Springfox.
Suggested Approach (Short Term)
- Use the current Swagger generation REST call to save the Swagger document
- Check in the Swagger document in "src/main/resources/openapi/openapi.yaml"
- Delete the Springfox annotations
Advantages:
- Easy to do!
- Does not risk changing the interfaces
- Gets us off Springfox
Disadvantages:
- The Swagger document must be manually kept aligned with the code
- The REST call for generating the Swagger will not work any more
Suggested Approach (Long Term)
- Update the Swagger document in "src/main/resources/openapi/openapi.yaml" to be OpenAPI 3.0 compatible
- Generate the REST interface code from the OpenAPI specifications (See ACM approach below)
- Modify the code to use the generated REST code
- Create contract testing stubs for API and PAP
Advantages:
- The Swagger document becomes the source document
- The Swagger generation REST interface will work again
- We can support a full implementation of each interface for production and a stubbed implementation for contract testing
Disadvantages:
- We must be sure to preserve backward compatibility on the API/PAP interfaces
- This will take development effort
See - POLICY-4431Getting issue details... STATUS for API and - POLICY-4432Getting issue details... STATUS for PAP.
CLAMP ACM
The situation in CLAMP ACM is somewhat different because we are updating the ACM APIs in London anyway to make the REST interface to ACM more compatible with REST principles, see - POLICY-3368Getting issue details... STATUS , a JIRA resulting from review comments on the REST interface during the original ACM development. Therefore, for ACM we will use an "OpenAPI First" approach in ACM in London and trial it