Swagger配置及使用

Swagger

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

1、新建 Springboot 项目

2、编写 HelloWord(新建一个 controller，新建一个 HelloControl.java)

@RestController
public class HelloController {

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

启动访问 localhost：8080/hello

3、导入 Swagger 依赖（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、编写 SwaggerConfig（新建一个 config，创建 SwaggerConfig.java配置类）

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

5、访问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.youkuaiyun.com/Xiao_tongtong?spm=1010.2135.3001.5421", "519395917@qq.com");
    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常用注解：

作用都是在文档上注释来解释各个接口属性的意思

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

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

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

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

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

总结：

• 导依赖 + 配置 swagger + 写注解
• 重点：一定要设置 Swagger 接口文档的显示环境，否则他人可以访问到！