There are a number of issues in the area of OpenAPI and Swagger. They are all gathered together on the Epic POLICY-4123 - Getting 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-4141 - Getting issue details... STATUS and POLICY-4142 - Getting issue details... STATUS .

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 - Getting 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-4404 - Getting issue details... STATUS , 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 - Getting issue details... STATUS for API and POLICY-4432 - Getting 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-3368 - Getting 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


  • No labels