OpenAPI 3.0 Migration

Owned by Liam Fallon
Last updated: Nov 09, 2022
2 min read

There are a number of issues in the area of OpenAPI and Swagger. They are all gathered together on the Epic POLICY-4123: R12: OpenAPI Adaption and Swagger CleanupClosed.

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-4141: Comply with Metadata driven Architectural PrinciplesClosed and POLICY-4142: Generate APIs from OpenAPI specificationsClosed.

In the current implementation, we are using SpringFox to generate the 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-4142: Generate APIs from OpenAPI specificationsClosed. 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-4404: Remove SpringFox from Policy FrameworkClosed, the Swagger is generated by Springfox.

Suggested Approach (Short Term)

  1. Use the current Swagger generation REST call to save the Swagger document

  2. Check in the Swagger document in "src/main/resources/openapi/openapi.yaml"

  3. 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)

  1. Update the Swagger document in "src/main/resources/openapi/openapi.yaml" to be OpenAPI 3.0 compatible

  2. Generate the REST interface code from the OpenAPI specifications (See ACM approach below)

  3. Modify the code to use the generated REST interface code

  4. 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-4431: Open API Specifications as a Source Artifacts APIClosed for API and POLICY-4432: Open API Specifications as a Source Artifacts PAPClosed 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-3368: Revise Rest API conventions and structureClosed, 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