...
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
Jira |
---|
server | ONAP Jira |
---|
columnIds | issuekey,summary,issuetype,created,updated,duedate,assignee,reporter,priority,status,resolution |
---|
columns | key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution |
---|
serverId | 425b2b0a-557c-3c0c-b515-579789cceedb |
---|
key | POLICY-41424141 |
---|
|
and
Jira |
---|
server | ONAP Jira |
---|
columnIds | issuekey,summary,issuetype,created,updated,duedate,assignee,reporter,priority,status,resolution |
---|
columns | key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution |
---|
serverId | 425b2b0a-557c-3c0c-b515-579789cceedb |
---|
key | POLICY-4142 |
---|
|
.
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
Jira |
---|
server | ONAP Jira |
---|
columnIds | issuekey,summary,issuetype,created,updated,duedate,assignee,reporter,priority,status,resolution |
---|
columns | key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution |
---|
serverId | 425b2b0a-557c-3c0c-b515-579789cceedb |
---|
key | POLICY-4142 |
---|
|
. 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
Jira |
---|
server | ONAP Jira |
---|
columnIds | issuekey,summary,issuetype,created,updated,duedate,assignee,reporter,priority,status,resolution |
---|
columns | key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution |
---|
serverId | 425b2b0a-557c-3c0c-b515-579789cceedb |
---|
key | POLICY-4404 |
---|
|
, 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 interface 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
Jira |
---|
server | ONAP Jira |
---|
columnIds | issuekey,summary,issuetype,created,updated,duedate,assignee,reporter,priority,status,resolution |
---|
columns | key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution |
---|
serverId | 425b2b0a-557c-3c0c-b515-579789cceedb |
---|
key | POLICY-4431 |
---|
|
for API and Jira |
---|
server | ONAP Jira |
---|
columnIds | issuekey,summary,issuetype,created,updated,duedate,assignee,reporter,priority,status,resolution |
---|
columns | key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution |
---|
serverId | 425b2b0a-557c-3c0c-b515-579789cceedb |
---|
key | POLICY-4432 |
---|
|
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
Jira |
---|
server | ONAP Jira |
---|
columnIds | issuekey,summary,issuetype,created,updated,duedate,assignee,reporter,priority,status,resolution |
---|
columns | key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution |
---|
serverId | 425b2b0a-557c-3c0c-b515-579789cceedb |
---|
key | POLICY-3368 |
---|
|
, 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