...

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

In the current implementation, we are using SpringFox to generate teh 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 API and Policy PAP

The current Policy API and Policy PAP interfaces are stable. The issue here is  

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

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