Swagger framework use step notes

1. Import MAVEN

<!-- 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 configuration class

3. Write the configuration class

code show as below:

package com.cy.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
# contact包不要导入错误
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2  //开启swagger2
public class SwaggerConfig {
    
    
    //配置了swagger的Docket的bean实例
    @Bean
    public Docket docket(){
    
    
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
    //配置swagger信息=apiInfo
    private ApiInfo apiInfo(){
    
    
        //contact 是作者信息
        Contact contact = new Contact("冷山集", "https://blog.csdn.net/weixin_40597409", "[email protected]");
        return new ApiInfo(
                "冷山集的Swagger API文档",
                "这是一个描述",
                "v1.0",
                "https://blog.csdn.net/weixin_40597409",
                 contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }
}

4. Write the Hello class

code show as below:

package com.cy.swagger.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {
    
    

    @RequestMapping("/hello")
    public String Hello(){
    
    
        return "hello";
    }

}

5. Run the program to check whether swagger is successfully started

Enter the link: http://localhost:8080/swagger-ui.html

6.Swagger configuration scan interface

Update the configuration class code as follows:

package com.cy.swagger.config;



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

import java.util.ArrayList;

@Configuration
@EnableSwagger2  //开启swagger2
public class SwaggerConfig {
    
    
    //配置了swagger的Docket的bean实例
    @Bean
    public Docket docket(){
    
    
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                
                .select()
                // RequestHandlerSelectors配置要扫描的接口方式
                // .basePackage指定要扫描的包
                // .any()全部扫描  .none()全部不扫描
                // withClassAnnotation() 扫描类上的注解,参数是一个注解的反射对象(.class)
                // withMethodAnnotation() 扫描类上的注解
                .apis(RequestHandlerSelectors.basePackage("com.cy.swagger.controller"))
                // .paths() 过滤
                // .paths(PathSelectors.ant("/cy/**"))
                .build();
    }

    //配置swagger信息=apiInfo
    private ApiInfo apiInfo(){
    
    
        //contact 是作者信息
        Contact contact = new Contact("冷山集", "https://blog.csdn.net/weixin_40597409", "[email protected]");
        return new ApiInfo(
                "冷山集的Swagger API文档",
                "这是一个描述",
                "v1.0",
                "https://blog.csdn.net/weixin_40597409",
                 contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }

}

Configure whether to start Swagger

@Bean
    public Docket docket(){
    
    
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // .enable(false) 是否启动Swagger
                .enable(false)
                .select()
                // RequestHandlerSelectors配置要扫描的接口方式
                // .basePackage指定要扫描的包
                // .any()全部扫描  .none()全部不扫描
                // withClassAnnotation() 扫描类上的注解,参数是一个注解的反射对象(.class)
                // withMethodAnnotation() 扫描类上的注解
                .apis(RequestHandlerSelectors.basePackage("com.cy.swagger.controller"))
                // .paths() 过滤
                // .paths(PathSelectors.ant("/cy/**"))
                .build();
    }

Extended topic:

Q: I only want to use swagger in production and not use it when publishing. How to do it?

Ideas:
1. Determine whether it is a production environment flag=false
2. Inject the enable() parameter

1. Create two new configuration files

2. Perform file configuration The configuration
here is to select which environment to activate (here is port 8081 under dev)

3. Set the configuration
code as follows:

package com.cy.swagger.config;



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

import java.util.ArrayList;

@Configuration
@EnableSwagger2  //开启swagger2
public class SwaggerConfig {
    
    
    //配置了swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){
    
    
        //设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev","test");
        //获取项目的环境:
        //通过environment.acceptsProfiles()判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cy.swagger.controller"))
                .build();
    }

    //配置swagger信息=apiInfo
    private ApiInfo apiInfo(){
    
    
        //contact 是作者信息
        Contact contact = new Contact("冷山集", "https://blog.csdn.net/weixin_40597409", "[email protected]");
        return new ApiInfo(
                "冷山集的Swagger API文档",
                "这是一个描述",
                "v1.0",
                "https://blog.csdn.net/weixin_40597409",
                 contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }

}

7. Configure grouping

Add a line of code under the configuration file:

 .groupName("冷山集")

Restart the server login interface to see:

---

So if you find that the Docket object corresponds to a group, you can add the following code to the SwaggerConfig configuration class:

 @Bean
    public Docket docket1(){
    
    
        return new Docket(DocumentationType.SWAGGER_2).groupName("冷山集1");
    }

    @Bean
    public Docket docket2(){
    
    
        return new Docket(DocumentationType.SWAGGER_2).groupName("冷山集2");
    }

    @Bean
    public Docket docket3(){
    
    
        return new Docket(DocumentationType.SWAGGER_2).groupName("冷山集3");
    }

Restart the server login page to find:

8. Entity class configuration

Create a User object under the pojo package: the
code is as follows

package com.cy.swagger.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体类")
public class User {
    
    
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
}

Then edit HelloController, the code is as follows:

package com.cy.swagger.controller;

import com.cy.swagger.pojo.User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {
    
    

    @GetMapping("/hello")
    public String Hello(){
    
    
        return "hello";
    }

    //只要接口中.返回值存在实体类,它就会被扫描到Swagger中
    @PostMapping("/user")
    public User user(){
    
    
        return new User();
    }
}

Restart the server:

Other comment formatting parameters:

@ApiParam("user name")
@ApiOperation("hello control class user")

@ApiOperation("hello控制类的user")
    @PostMapping("/user2")
    public User user2(@ApiParam("用户名") String username){
    
    
        return new User();
    }

9. Summary

• You can add annotation information to some more difficult to understand interfaces or attributes through Swagger
• Real-time update of interface documentation
• Can be tested online

Note:

Close Swagger when it is officially released. (For security reasons, and to save running memory)