Rest API- Swagger Documentation

Swagger Documentation

Swagger is a set of tools built around the OpenAPI Specification that helps developers design, build, document, and consume RESTful web services. It allows developers to describe the structure of their APIs in a standardized format, making it easier for both humans and computers to understand and interact with the APIs.

Step 1

Add Swagger Dependencies in pom.xml


Step 2

Swagger URL: http://localhost:8090/swagger-ui/index.html

To generate Swagger documentation, simply add the following dependencies to your pom.xml, start the Spring Boot application, and then access the specified URL in your browser.

 

To Customize Swagger Documentation

In this document we applied swagger annotations in three levels

1.application level

2.controller level

3.Dto leve

application level



@OpenAPIDefinition: This annotation is used to provide metadata about your API. It's typically used in Spring applications to generate OpenAPI (formerly Swagger) documentation. Within this annotation, you provide information such as the title, description, version, contact, and license of your API.

@Info: This annotation is nested within @OpenAPIDefinition and contains information about your API, such as its title, description, version, contact information, and license

 

  • ·         title: The title of your API, which is "Loan microservices REST API Documentation" in this case.
  • ·         description: A description of your API, which is "Accounts microservices REST API Documentation" in this case.
  • ·         version: The version of your API, which is "v1" in this case.
  • ·         contact: Contact information for the person or team responsible for the API. It includes the name ("klinton") and email ("klintonece@gmail.com").
  • ·         license: Information about the license under which the API is distributed. It's set to "Apache 2.0" in this case.

Controller level


@Tag: Meta data about Rest Controller

  • name: Name of the controller
  • description: purpose of this controller

Description for each Rest API Methods in controller.


@Operation: This annotation is used to provide metadata about the operation or method. In this case:

  • ·         summary: Provides a brief summary of what the operation does, which is "Create Account Rest API".
  • ·         description: Provides a more detailed description of the operation.

 

@ApiResponses: This annotation allows you to define multiple possible responses for the operation. In this case:

@ApiResponse: Specifies a single possible response.

  • ·         responseCode: The HTTP response code, such as "201" for Created or "500" for Internal Server Error.
  • ·         description: A description of the response.
  • ·         content: Defines the content of the response, including the schema (data model) of the response body. Here, it specifies that for a 500 response, the response body will be an instance of ErrorResponseDTO

 DTO Level

Request Body description in Swagger API



@Schema: This annotation is used for OpenAPI (formerly Swagger) documentation purposes. It provides metadata about the schema of the DTO.

 

  • ·         name: Specifies the name of the schema, which is "Account" in this case.
  • ·         description: Provides a description of the schema.

 Output



 

Comments

Post a Comment

Popular posts from this blog

Microservices Communication – Feign Client

Image
  Microservices Communication – Feign Client Spring cloud OpenFeign provides OpenFeign Integration for spring boot apps through auto configuration and binding to the spring environment Without feign client in spring boot application, we can use Rest Template to call user service. To use Feign client we need to add spring-cloud-starter-OpenFeign dependency in pom.xml In our project, if one micro-service accesses another microservice then is called inter-service communication ·          Rest Client (External Communication) ·          Web Client(External Communication) ·          Feign Client(Internal Communication) When we use feign client we do need to configure API URL to access. Using the API name we can access API (Feign client will get API URL from Service Registry) Feign Client is part of Spring Cloud Netflix Libraries Open Feign is decla...
Read more

Service Discovery - Eureka Server and Client

Image
  Steps to Build Service Discovery EUREKA SERVER Step 1 Create a Spring boot project and add dependency Step 2 Add the spring-cloud-starter-netflix-eureka-server dependency to your pom.xml file 1.        Web 2.        Actuator 3.        Eureka dependency Step 3 In your main application, annotate it with @EnableEurekaServer .this will enable Eureka Server Functionality Step 4 Configure Below properties in application. 1.        Application name 2.        Port number 3.        Enable Actuator 4.        Erueka Configuartion ·          Register with Eureka ·          Fetch Register ·          Default Zone URL Build and run the Eureka Server: Open a browser and ...
Read more