ADR: Upgrade swagger version from swagger 2.0 to swagger 3.0 (OpenAPI 3)

Status

• Proposed
• Under review
• Approved
• Retired

Context & Scope

OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including: endpoints, optional parameters, authentication methods and contact/ license information.

The latest swagger version has been released with name OpenAPI 3.0

Why is the upgrade required

The OpenAPI 3.0 offers several new features such as servers field, which enables us to write automation on top of it. Let's say if you have a tool which scans the REST endpoint exposed by your service for various reasons, it can consume the openapi.json directly and skim through all the end points in that service

Scope

All the services

Trade-off Analysis

• Are there any breaking changes in REST API doc while upgrading from swagger 2.0 to swagger 3.0: NO
• Are there any breaking changes in UI: There are no breaking changes in UI per say. If anything, it has become more fluid and lightweight.
• How involved are the code changes: For most of the services, it's a matter of upgrading the maven package with minor changes here and there. For few services the changes can be more involved as some the the tags have changes between 2.0 and 3.0, like @Api has becom @Tag. More details are documented here: https://springdoc.org/#migrating-from-springfox
• Would the URL change: YES. The swagger home page for 2.0 is swagger-ui.html, while for 3.0, it is swagger-ui/index.html. However, we also have an explicit endpoint /swagger (or equivalent) which can be leveraged to abstract the underlying swagger URL. Users can continue visiting the swagger homepage by hitting /swagger endpoint.

Decision

cc: @kibattul @madhurtanwani