Swagger2: the interaction artifact of front and rear end

Catalog

Preface

It is believed that many individuals and companies have used the front-end and back-end separation to develop or are on the way to the front-end and back-end separation.
In front end and back end separation, the most headache of back-end staff is to write various API documents to the front-end, and to write comments (I don't want to write comments, I will complain about no comments when I look at other people's code).
But a tool makes it possible for us to integrate the two in our development.
It's swagger 2, the artifact we're going to introduce today.
It can not only make annotation and interface "fit", but also make annotation itself an art.
No more nonsense, we're on the right track.

Integration of SpringBoot and Swagger2

First, we open IDEA (or Eclipse), and create our demonstration project with Spring Initializer.
springboot-swagger
Here are the steps to create a project (IDEA)



Check the modules we need


Finally, click Finish to finish the creation of our project

Let's first add the coordinates of swagger2 in the pom file where we created the project (dependency)

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.0.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.laoqin</groupId>
    <artifactId>springboot-swagger</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>springboot-swagger</name>
    <description>Demo project for Swagger</description>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
            <exclusions>
                <exclusion>
                    <groupId>org.junit.vintage</groupId>
                    <artifactId>junit-vintage-engine</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <!--swagger Interface-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>
        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

Then create our configuration class in the package SRC > java > com.laoqin.springboot.swagger.config

package com.laoqin.springboot.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    @Bean
    public Docket restApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.laoqin.springboot.swagger.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("My Swagger project")
                .description("Here are some introduction of the project")
                .termsOfServiceUrl("https://blog.csdn.net/itkfdektxa")
                .version("1.0")
                .build();
    }
}

Finally, we write several requests under the controller package and annotate them with annotations.

package com.laoqin.springboot.swagger.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

/**
 * @Description
 * @Author QinLing
 * @Date 2019/10/24 14:42
 **/
@Slf4j
@RestController("/user")
@Api("User correlation")
public class UserController {

    @ApiOperation("Query users-according to id")
    @GetMapping("/{id}/get")
    public String getUserById(@PathVariable Integer id){
        return "xxx";
    }

    @ApiOperation("delete user-according to id")
    @DeleteMapping("/{id}/delete")
    public String deleteUserById(@PathVariable Integer id){
        return "xxx";
    }
}

Run our SpringBoot project and visit the following address

Swagger UI address

Get our API specification

The above is the basic operation of our integration. Next, we can happily throw the address to the front desk.
Because our interface annotation is generally only at the method level, if you want to generate documents in more detail, you can continue to read the third topic.

Notes on Swagger2

@Api: decorate the whole class to describe the function of Controller
@ApiOperation: a method, or an interface, that describes a class
@ApiParam: single parameter description
@ApiModel: receiving parameters with objects
@ApiProperty: a field describing an object when receiving parameters with the object
@ApiResponse: HTTP response one of the descriptions
@ApiResponses: overall description of HTTP response
@ApiIgnore: use this annotation to ignore this API
@ApiError: information returned when an error occurs
@ApiImplicitParam: a request parameter
@Apiimplicit params: multiple request parameters

That's what Swagger2 is all about.