OpenAPI Specification v. 3+ Introduction

Mental Checklist

Background

In the heat of coding and meeting strict deadlines, most of us as developers forget to think about documentation. In my case my manager popped the question on the day of the demo. There was utter panic when he shot down our out of the box swagger UI. What followed was a learning experience for me. I do not consider myself an expert at coding, yet (wink wink). I love what I do and have too much passion for coding. This chiding incident led me to deep dive into documentation standards in the industry. Since we had already built the microservices functionality. Now, we had to engineer the swagger UI to look like a professional API document.

Introduction

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. (Reference)

A quick guide to swagger annotations

@Tag @Operation @ApiResponses @Schema

I would also encourage you to explore io.swagger.v3.oas.annotations source package.

How can I pass JWT token in swagger

What I learnt is that one cannot pass JWT token in the swagger UI header. <LOST?> This is a tricky matter. On trying to google it you will be lost in a vicious forums of GIT issues. Do not fret. The solution is mentioned both in official Swagger and Spring doc link https://springdoc.org/faq.html

You want to enable a Authorize button on your Swagger UI

Steps to enable Authorize button

Step 1 : At Controller add @SecurityRequirement

@Operation(summary = “Summary”, description = “<b>Implementation Notes</b> <br/>Long description”, tags = {“reports” }, security = { @SecurityRequirement(name = “bearer-key”) })

Step 2 : At Open API configuration

List<Server> serverList = new ArrayList<Server>();
Server qaServer = new Server();
qaServer.setDescription(“INT”);
qaServer.setUrl(“URL-int");
Server stgServer = new Server();
stgServer.setDescription(“STG”);
stgServer.setUrl(“URL-stg");
serverList.add(qaServer);
serverList.add(stgServer);
return new OpenAPI().servers(serverList).components(new Components().addSecuritySchemes(“bearer-key”,
new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme(“bearer”).bearerFormat(“JWT”))
).info(new Info().title(“Pro API”).description(
“Pro description”));

Enabling Cross-origin resource sharing (CORS)

This was solved using @CrossOriginin controller

MUST read —

How can I use GIT pages for swagger UI

Further reading- https://github.com/peter-evans/swagger-github-pages

Previously published at https://medium.com/@nikitajos/openapi-swagger-v3-and-microservices-776df1bda93c