Swagger for API documentation

Swagger is an open-source software framework that helps developers design, build, document, and consume RESTful APIs. Swagger documentation is a representation of a RESTful API that is created using the Swagger specification. The Swagger specification is a standard interface description language for REST APIs. It allows developers to describe the structure of their APIs and generate documentation in a human-readable format. The generated Swagger documentation includes information about the API endpoints, request and response parameters, and other relevant details. It can be used by other developers to understand the functionality of the API and make calls to it.

Swagger features

Swagger documentation provides a number of features, including:

1. Interactive documentation: Allows developers to try out API calls and see the responses in a browser-based UI.
2. API Definition: Provides a clear, concise and human-friendly definition of what the API does, its endpoints, parameters, and expected responses.
3. Code Generation: Generates server and client code in multiple programming languages to help speed up the development process.
4. Validation: Automatically validates API requests and responses to ensure they meet the API’s specification.
5. Documentation Generation: Automatically generates API documentation in various formats, including HTML, JSON, and YAML.
6. Collaboration: Supports collaboration between API creators, developers, and stakeholders, by providing a centralized location for API documentation.
7. Testing: Provides an environment for testing API calls and ensuring that they meet the desired behavior.
8. Versioning: Supports versioning of APIs and allows users to view and work with multiple versions of an API.

Supported languages

Swagger documentation supports several programming languages including:

1. Java
2. Node.js
3. PHP
4. Python
5. Ruby
6. Go
7. C#
8. Scala
9. Perl

It also supports creating API documentation in YAML and JSON.

Enable Swagger in Spring boot

To enable Swagger documentation in a spring boot application, you need to follow these steps:

1. Add the springfox-swagger2 and springfox-swagger-ui dependencies to the project.
2. Enable the Swagger support in your Spring Boot application by annotating your configuration class with @EnableSwagger2.
3. Create a Docket bean to configure the Swagger properties, such as the API version, title, and description.
4. Annotate your RESTful APIs with appropriate Swagger annotations, such as @Api, @ApiOperation, @ApiParam, etc.
5. Run the Spring Boot application and access the Swagger UI at the URL http://localhost:port/swagger-ui.html, where port is the HTTP port on which your application is running.

Here is a sample code to enable Swagger documentation in a spring boot application:

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

For details refer:

Setting Up Swagger 2 with a Spring REST API | Baeldung

Documenting a Spring REST API Using OpenAPI 3.0 | Baeldung