Using Swagger 2 in Spring Boot

The most popular API tool in the world

Swagger is the world's largest OpenAPI specification (OAS) API development tool framework.

Implement development throughout the API life cycle, from design and documentation to testing and deployment.

1. What is Swagger 2

Swagger is a powerful and easy-to-use API developer tool suite for teams and individuals, supporting development from design and documentation to testing and deployment throughout the API life cycle. Swagger is used to better implement and visualize APIs defined in the specification.

2. Why use Swagger 2

  • Design is the foundation of API development. Swagger 2 makes API design easy and provides developers, architects and product owners with easy-to-use tools.
  • Swagger 2 provides tools for rapid prototyping and API functionality building.
  • Swagger2 provides a series of solutions for generating, visualizing and maintaining API documents.
  • Swagger2 tools allow you to easily and quickly create, manage and execute API tests.

3. How to use Swagger 2

3.1 Configuration Swagger2

1. Adding Swagger 2 dependencies to pom.xml

        <!-- swagger2 rely on -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.5.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

2. Create configuration classes for Swagger 2

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * Configure whether Swagger2 is turned on
     */
    @Value("${swagger.enable}")
    private boolean enableSwagger;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enableSwagger)    // enable(true) means to open Swagger
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .title("Development framework Demo")
                        .description("Add, delete, modify and check interfaces of user and merchant information tables.")
                        .version("1.0")
                        .contact("lxiao")
                        .build());
    }
}

@ Configuration annotations are used to make spring load configuration classes. @ Enable Swagger 2 is used to open Swagger 2.

In the configuration class of Wagger2, create the Bean of Docket by creating the createRestApi() function.

enable() is used to open and disable Swagger. Swagger is turned on if the parameter is true, and Swagger is disabled if the parameter is false. Swagger can be enabled in the application configuration to control the local development environment and disabled in the test and production environments.

The select() function returns an ApiSelectorBuilder instance to control which interfaces are exposed to Swagger for presentation.

apis() selects which interfaces to use for Swagger. In the example, the interface under the com.example.demo.controller package is used for Swagger.

The apiInfo() function is used to create the basic information of the API.

Start the project after configuring SwaggerConfig, access http://localhost:8080/swagger-ui.html .

This is the swagger-ui interface, where you can see the API information you just configured.

3.2 Introduction to Swagger 2 Annotations

1.Swagger2 commonly used annotations to add document content.

@Api(value="user controller",tags={"User Operating Interface"})
@RestController
@RequestMapping("api/user")
public class UserController {

    @RequestMapping(value = "/" , method = RequestMethod.POST)
    @ApiOperation(value = "Adding user interfaces")
    public Object add(@RequestBody User user){
        //... Specific interface implementation
    }
}

@ Api (value = message, tags = {message}) is used for classes to indicate that the class is a swagger resource.

@ ApiOperation (value = message) is used for methods to represent the operation of an http request.

Start the project to see the effect:

@ApiModel(value="User Object",description="User Object user")
public class User {
    
    @ApiModelProperty(value = "user ID")
    private String id;
    
    @ApiModelProperty(value = "User name")
    private String userName;
    
    @ApiModelProperty(value = "User password")
    private String userPassword;
}

@ ApiModel (value = message, description = message) is used for class representation to explain the class and for parameter reception with entity class.

@ ApiModelProperty (value = message) is used for methods, fields. Represents a description of the model attribute or a change in data operation.

Start the project to see the effect:

    @RequestMapping(value = "/" , method = RequestMethod.GET)
    @ApiOperation(value = "Query User Interface")
    public Object query(@ApiParam(name="id",value="user id",required=true) String id){
        //... Specific interface implementation
    }

@ ApiParam (name = message, value = message, required = true) is used for methods, parameters, field descriptions, indicating the addition of metadata to parameters (description or whether it is necessary to fill in, etc.).

Start the project to see the effect:

There are many other Wagger annotations that you can try and learn on your own.

4. Pay attention to my Wechat Public Number, check out more articles, and receive my articles as soon as possible.

Have you learned how to use Swagger 2 in Spring Boot?

Tags: Java Spring xml Attribute

Posted on Sat, 07 Sep 2019 03:10:33 -0700 by please_explain