Swagger configuration and use

Swagger

	一个接口文档工具，可以自动直接扫描写的所有接口，并且支持调试。

1. Create a new Springboot project

2. Write HelloWord (create a new controller, create a new HelloControl.java)

@RestController
public class HelloController {
    
    

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

Start accessing localhost: 8080/hello

3. Import Swagger dependency (pom.xml)

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

4. Write SwaggerConfig (create a new config, create SwaggerConfig.java configuration class)

@Configuration
@EnableSwagger2  //开启 Swagger2
public class SwaggerConfig {
    
    }

5. Visit the main interface of Swagger

http://localhost:8080/swagger-ui.html

6、 SwaggerConfig

package 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
public class SwaggerConfig {
    
    

  //配置多个文档分组
  //    @Bean
  //    public Docket docket1() {
    
    
  //        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
  //    }

  //配置了Swagger的Docket的bean实例
  @Bean
  public Docket docket(Environment environment) {
    
    

    //设置需要显示的Swagger的环境比如dev ，test， pro 环境
    Profiles profiles = Profiles.of("dev");
    //通过environment.acceptsProfiles判断是都在当前自己设置的环境中
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)
      //在自己的环境中，true就启动Swagger
      .enable(flag)
      .groupName("tong")
      .apiInfo(apiInfo())
      .select()

      //RequestHandlerSelectors:配置要扫描接口的方式
      //basePackage:指定要扫描的包   
      // ==========一般只用basePackage=======
      //any():扫描所有
      //none():全部不扫描
      //withClassAnnotation(Controller.class):用反射的方式扫描类上有@Controller注解的
      //withMethodAnnotation(RequestMapping.class)：用反射的方式扫描类上有@RequestMapping注解的

      //扫描 swagger.controller下的接口
      .apis(RequestHandlerSelectors.basePackage("swagger.controller"))
      // 配置如何通过path过滤,即这里只扫描请求以/hello开头的接口
      //                .paths(PathSelectors.ant("/hello/**"))

      .build();
  }

  public ApiInfo apiInfo() {
    
    
    //作者信息
    Contact DEFAULT_CONTACT = new Contact("TomYe", "https://blog.csdn.net/Xiao_tongtong?spm=1010.2135.3001.5421", "[email protected]");
    return new ApiInfo(
      "TomYe的Swagger",
      "一个人走的快",
      "v1.0",
      "urn:tos",
      DEFAULT_CONTACT,
      "Apache 2.0",
      "http://www.apache.org/licenses/LICENSE-2.0",
      new ArrayList());

  }
}

Swagger common annotations:

The role is to comment on the document to explain the meaning of each interface attribute

  注解在Controller类上
  @Api(tags = "用户登录接口")

  注解在方法上面
  @ApiOperation("登录方法")

  注解在实体类上
  //给实体类注释别名
  @ApiModel("用户实体类")

  注解在实体类属性上
  //给字段注释别名
  @ApiModelProperty("微信昵称")

tips: 实体类不是通过注解的方式扫描到的，
而是通过配置类里面扫描 Swagger.controller的所有接口，
只要接口中有返回的实体类，那么该实体就会被扫描到。

Summarize:

• Import dependencies + configure swagger + write annotations
• Important: Be sure to set the display environment of the Swagger interface document, otherwise others can access it!