ADR - Swagger: Using springdoc-openapi for swaggers APIs

Decision Title

Swagger Sanity Phase 2: Using springdoc-openapi for swaggers APIs

Status

• Proposed
• Approved
• Implementing (incl. documenting)
• Testing
• Released

Context

• The swagger APIs are maintained as part of each service, for instance Storage Swagger Controller.
• The swagger doc is handwritten and manually maintained, for instance Storage Service Swagger.

Assumption

The swagger for all services is in version 3 already.

Problem statement

The cost of maintenance of the swagger doc is high. We have stale swaggers in the system already.

Proposed solution

We have the following frameworks that will help lower the cost of upkeep of swagger.

1. springdoc-openapi
2. springdoc-openapi-webflux-ui

Scope / Acceptance Criteria

The above effort will encapsulate the following

1. Controller, Model improvement to retain the swagger information that is present today.
2. The swagger endpoint path will be a consistent as we see it today.
3. The deprecation of the swagger controllers we maintain should be seamless experience for the user.

Target Release

TBD

FAQ

**1. How will we manage migration to next generation of swaggers, when available. ** We will count on Spring Boot's adaptation of the next generation to be back compatible.

**2. Will there be regressions in the existing experience? ** No, as specified in the Scope.

Useful references

1. https://www.baeldung.com/spring-rest-openapi-documentation
2. Adding annotations that will contain the description which the current Swagger has. https://www.baeldung.com/swagger-set-example-description#1-add-description-to-methods-and-parameters

Owner

Please contact @komakkar