使用Swagger自动生成Api文档

使用Swagger自动生成Api文档

1、Swagger简介

• 号称世界上最流行的Api框架；
• RestFul Api 文档在线自动生成工具=> Api文档与Api定义同步更新
• 直接运行，可以在线测试API接口；
• 支持多种语言：（Java，Php…）

官网：https://swagger.io/

在项目中使用Swagger需要springfox；

• swagger2
• ui

2、SpringBoot集成Swagger

1、新建一个SpringBoot-web项目

2、导入相关依赖

<!--swagger相关依赖-->
		<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>

3、编写一个Hello工程

4、配置Swagger==>Config

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

5、测试运行：

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

若报空指针异常，原因是springboot版本过高！

配置application.yaml

# 匹配策略
spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

3、编写API接口文档

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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 {

    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket restApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("接口1")
                .apiInfo(apiInfo())
                //默认为true,若改为false则不能在浏览器中访问
//                .enable(false)
                
                .select()
                //RequestHandlerSelectors , 配置要扫描接口的方式
                //basePackage : 指定要扫描的包   basePackage("com.jin.swagger.controller")
                //any() : 扫描全部
                //none() : 不扫描
                //withClassAnnotation : 扫描类上的注解,参数是一个注解的反射现象
                //withMethodAnnotation : 扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.jin.controller"))
                //过滤什么路径
//              .paths(PathSelectors.ant("/jin/**"))
                .build();
    }

    @Bean
    public Docket restApi2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("接口2")
                .apiInfo(apiInfo2())
                .select()
                //none() : 不扫描
                .apis(RequestHandlerSelectors.none())
                .build();
    }

    //配置swagger显示信息
    private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new Contact("酷小亚", "https://blog.csdn.net/weixin_45737330", "384921322@qq.com");
        return new ApiInfo(
                "SwaggerAPI文档————标题！！",
                "不到园林，怎知春色如许————文档描述！",
                "1.0",
                "http://localhost:8080/swagger-ui.html",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());

    }
    private ApiInfo apiInfo2(){
              return new ApiInfo(
                "接口2",
                "接口2描述！",
                "2.0",
                "http://localhost:8080/swagger-ui.html",
                null,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

4、多环境配置Swagger

• 判断是不是生成环境 flag = false

  application.yaml

  spring:
    profiles:
      active: dev
  

  application-dev.yaml

  server:
    port: 8081
  

• 注入enable（flag）

   //配置了Swagger的bean实例
      @Bean
      public Docket docket(Environment environment){
  
          //设置要显示的Swagger环境:可配置多环境
          Profiles profiles = Profiles.of("dev","test");
          //通过 environment.acceptsProfiles 判断是否处在自己设定的环境当中
          boolean flag = environment.acceptsProfiles(profiles);
  		......
      
      }     
              
  

  测试运行：

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

  配置API文档的分组

  .groupName("酷小亚")
  

  如何配置多个分组；多个Docket实例即可

    @Bean
      public Docket docket1(){
          return new Docket(DocumentationType.SWAGGER_2).groupName("A");
      }
      @Bean
      public Docket docket2(){
          return new Docket(DocumentationType.SWAGGER_2).groupName("B");
      }
      @Bean
      public Docket docket3(){
          return new Docket(DocumentationType.SWAGGER_2).groupName("C");
      }