springBoot integrated API documentation tool Swagger2

A, Swgger Introduction

1. official website

https://swagger.io/

2. Introduction

Swagger is a standardized and complete framework for generating, description, and visualization calls for RESTful Web services.
Swagger's goal is to define a standard REST API and language-independent interface, people can have a computer and need to access source code, documents, or monitoring network traffic can discover and understand the service capabilities. When properly defined by Swagger, the user can understand and use the remote service and remote service implementation logic minimal interaction. And for the underlying programming interfaces implemented similar, Swagger may have eliminated the guesswork call service.
3.Swagger advantages
support automatic generation of synchronization API documentation can be automatically generated after use Swagger directly through the code and simple configuration file, eliminating the need to manually write interface documentation for programmers, you can save time to write the document to learning new skills
provide web pages online test API, you can not require postman and other tools for interface testing, online testing parameters and format are determined, the set parameters directly in the web interface can be tested interfaces friends.

Two, springBoot integrated Swagger

1. Create a new springBoot, introduced its dependencies

　　　　<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2. Create a new class interface HelloController control, and create a new configuration class Swagger

Since this class is configured class, so add an annotation @ Configuration, Swgger Notes @ EnableSwagger2 indicate on swagger, you can do so simple to use Swagger, but all configurations execute the default option

In the browser root plus /swagger-ui.html, you can access the web-side API documentation

This picture shows all the default configuration, you can see the page is divided into four parts, the carrier interface section basic-error-controller is built-in, such as access to 404 pages or other default go this route, Hello-controller for us the new Controller, of course, we want to be configured as needed swagger and both sides need to let him have a simple tool to generate api

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo (apiInfo ())
                .select()
                // RequestHandlerSelectors configured to scan interface mode
                // basePackage indicates that the specified scan package
                .apis(RequestHandlerSelectors.basePackage("com.example.demo03.controller"))
                // paths have expressed the need for filtration path
                .paths(PathSelectors.any())
                .build();
    }

    apiInfo information // apiInfo for the configuration of the Swagger
    private ApiInfo apiInfo(){
        Contact contact = new Contact("liufuqiang", "https://cnblogs.com/LiuFqiang", "[email protected]");
        return new ApiInfo(
                "Outpatient drug analysis system background RESTful API documentation"
                "author:liufuqiang",
                "v1.0",
                "https://cnblogs.com/LiuFqiang",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

　　Here we have a simple configuration, Docket as an example of Swagger, by looking at the underlying source code, we can see there are some properties Docket

And we want to use a good Swagger need to configure these properties, such as modifying the basic information where the api, and specify the package needs to be scanned surface

Third, the context switch

While we were in normal development, there will be development and production environments, if the environment is on the line will be directly exposed to this document may not be good, we all want to have to change according to whether the project environment corresponding to open Swagger

api information unchanged, increase property Environment to monitor the environment of the project, if the development environment, set to open Swagger, if build environment, disable Swagger, such as where we build environment to enable 3030, the following screen appears:

Fourth, the documents are grouped

To the API documentation packet, when we were team development, it is best for each individual document will be grouped so that front-end developers,

When people develop, will automatically inject multiple instances Docket container for the spring,

We can see in the upper right corner a few more space because we inject the corresponding three examples, otherA and otherB Since we do not have any configuration, so there will be our first step in the default configuration page

Fifth, code comments

When we return data in the controller, if there is data involved pojo class, the class of this entity will be displayed on the model

@RestController
public class HelloController {

    @Autowired
    private HelloService helloService;

    @GetMapping("/getAllUser")
    public Student getAllUser(){
        return new Student();
        
    }
}

　Here we create a new entity class Student, have in HelloController class method returns the entity class

When people develop probably the most painful thing is to see the code written by someone else, there may be some field named others do not understand, all the comments in the code which will generate documentation