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 a button on your Swagger UI enable Authorize Steps to enable Authorize button At Controller add @SecurityRequirement Step 1 : (summary = “Summary”, description = “<b>Implementation Notes</b> <br/>Long description”, tags = {“reports” }, security = { (name = “bearer-key”) }) @Operation @SecurityRequirement At Open API configuration Step 2 : List<Server> serverList = ArrayList<Server>(); Server qaServer = Server(); qaServer.setDescription(“INT”); qaServer.setUrl(“URL- ); serverList.add(qaServer); serverList.add(stgServer); OpenAPI().servers(serverList).components( Components().addSecuritySchemes(“bearer-key”, SecurityScheme().type(SecurityScheme.Type.HTTP).scheme(“bearer”).bearerFormat(“JWT”)) ).info( Info().title(“Pro API”).description( “Pro description”)); new new int "); Server stgServer = new Server(); stgServer.setDescription(“STG”); stgServer.setUrl(“URL-stg" return new new new new Enabling Cross-origin resource sharing (CORS) This was solved using @CrossOriginin controller MUST read — Enabling Cross Origin Requests for a RESTful Web Service https://swagger.io/docs/open-source-tools/swagger-ui/usage/cors/ 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
