Intro

What is swagger?

Swagger, now known as the OpenAPI Specification, is a set of rules and conventions for documenting and defining RESTful APIs. It provides a standardized way to describe the endpoints, request and response formats, authentication methods, and other details of an API, making it easier for developers to understand and interact with the API.

The primary goal of Swagger/OpenAPI is to improve the communication and collaboration between API providers (developers creating the API) and API consumers (developers using the API). By providing a clear and structured documentation format, Swagger/OpenAPI helps developers understand how to make requests to the API, what data to expect in the responses, and any authentication or authorization requirements.

Key features of Swagger/OpenAPI include:

1. API Documentation: Swagger/OpenAPI allows you to create detailed and interactive documentation for your API. This documentation includes information about available endpoints, request parameters, response formats, error codes, and more.

2. API Definition: The specification is written in a machine-readable format, usually in JSON or YAML. This file serves as a single source of truth for the API's structure and behavior.

3. Code Generation: Swagger/OpenAPI tools can generate client libraries, server stubs, and other code artifacts for different programming languages, making it easier to implement and consume APIs.

4. Validation: API specifications can be used to validate requests and responses, helping to catch errors early in the development process.

5. Testing: Developers can use tools that leverage the specification to test their APIs automatically, ensuring that endpoints adhere to the defined contract.

6. Visualization: Swagger UI is a popular tool that reads the API specification and generates a user-friendly, interactive interface for exploring and testing the API endpoints.

7. Versioning: Swagger/OpenAPI supports versioning, allowing you to manage different versions of your API in a standardized way.

8. Third-Party Integrations: Many API management tools and frameworks support Swagger/OpenAPI natively, enabling seamless integration into various development and deployment workflows.

Overall, Swagger/OpenAPI helps streamline API development by providing a consistent and structured approach to documenting, designing, and implementing RESTful APIs.

Example

On the example of jbt, swagger described in spec module

Based on spec.xml(e.g. it describes server url, port number, description). After generation, all this information is created in the SwaggerConfiguration file

package com.knubisoft.api.spec.swagger;

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import io.swagger.v3.oas.annotations.servers.Server;
import io.swagger.v3.oas.annotations.servers.ServerVariable;
import org.springframework.context.annotation.Configuration;

import javax.annotation.Generated;

@Configuration
@OpenAPIDefinition(info =
                          @Info(title = "Java Backend Template API",
                                version = "0.0.1",
                                description = "Rest API based on java which provides read/write/delete/search operations for JBT project"),
                          servers = {
                              @Server(url = "http://localhost:{port}/",
                                        description = "The local API server",
                                        variables = {
                                            @ServerVariable(name = "port",
                                                            defaultValue = "8073",
                                                            description = "",
                                                            allowableValues = {"8073"})
            }
        )
    }
)
@SecurityScheme(
    name = "JWTAuth",
    type = SecuritySchemeType.HTTP,
    bearerFormat = "JWT",
    scheme = "bearer"
)
@Generated(value = "com.knubisoft.api.generator.Main", date = "2023-07-12T09:23:06.923561Z")
public class SwaggerConfiguration {
}