Swagger使用集成springboot

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。而Springfox-swagger,则可以通过扫描代码去生成这个描述文件，连描述文件都不需要再去维护了。所有的信息，都在代码里面了。代码即接口文档，接口文档即代码。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

1.添加坐标

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2.properties文件中设置（有些版本的springboot将SpringMVC 默认路径匹配策略从AntPathMatcher 更改为PathPatternParser，导致出现空指针异常）

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

3.在配置类或启动类上@EnableSwagger2

4.访问路径http://localhost:8080/swagger-ui.html

5. Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swagger

@Bean //配置docket以配置Swagger具体参数
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2);
}

6.通过apiInfo()属性配置文档信息

private ApiInfo apiInfo() {
    Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
    return new ApiInfo(
            "Swagger学习", // 标题
            "学习演示如何配置Swagger", // 描述
            "v1.0", // 版本
            "http://xxx.com", // 组织链接
            contact, // 联系人信息
            "Apach 2.0 许可", // 许可
            "许可链接", // 许可连接
            new ArrayList<>()// 扩展
    );

 docket实例关联该方法

 @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

7.配置扫描接口 以包的方式扫描

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.zxy.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/apesource开头的接口
      .paths(PathSelectors.ant("/apesource/**"))
      .build();
}

 其他扫描方式

通过方法上的注解扫描withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)

通过类上的注解扫描withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口

withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) 根据包路径扫描接口

any()  扫描所有，项目中的所有接口都会被扫描到
none()不扫描接口

 8.配置接口扫描过滤

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.xxx.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/apesource开头的接口
      .paths(PathSelectors.ant("/apesource/**"))
      .build();
}

any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制

9.配置API分组  如果没有配置分组，默认是default。通过groupName()方法即可配置分组

Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("hello") // 配置分组
       // 省略配置....
}

10.配置多个分组

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

常用注解

swagger通过注解生成接口文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用

 语法：@Api(tags="说明该类的作用，可以在UI界面上看到的注解"，value = "/类的访问路径", description = "类的文字描述")

@ApiOperation：描述一个类的一个方法，说明方法的作用

 语法：@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”）

@ApiImplicitParam：一个请求参数

语法：@ApiImplicitParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式”）

  ​