Swagger学习总结文档

Swagger

• Restful API 文档在线自动生成工具;API文档与API定义同步更新
• 直接运行,可以在线测试API接口,接口文档实时更新
• 支持多种语言
• 可以通过Swagger给一些比较难理解的属性或接口增加注释信息

官网

使用

项目使用需要springbox;

• swagger2
• ui

Spring Boot继承Swagger

以下内容代码存放在码云仓库

代码链接

新建SpringBoot-Web项目

导入相关依赖

// https://mvnrepository.com/artifact/io.springfox/springfox-swagger2
implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.10.5'


// https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui
implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.10.5'

// 此次使用的swagger 2.10.5版本,此版本删除了配置文件的@EnableSwagger2注解,需要用@EnableSwagger2WebFlux或者@EnableSwagger2WebMvc注解,故需要导入三个依赖,以下依赖二选一即可

// 1 使用@EnableSwagger2WebFlux注解

// https://mvnrepository.com/artifact/io.springfox/springfox-spring-webflux
implementation group: 'io.springfox', name: 'springfox-spring-webflux', version: '2.10.5'

// 2  使用@EnableSwagger2WebMvc注解

// https://mvnrepository.com/artifact/io.springfox/springfox-spring-webmvc
implementation group: 'io.springfox', name: 'springfox-spring-webmvc', version: '2.10.5'

编写工程代码,开启Swagger

@Configuration
// @EnableSwagger2WebFlux          //开启Swagger2WebFlux
@EnableSwagger2WebMvc          //开启Swagger2WebMvc
public class SwaggerConfig {
}

配置好以上内容,可以启动程序进行测试,

http://ip:port/swagger-ui.html

效果图如下:

配置Swagger

Swagger的bean实例Docket;

1. 配置Swagger信息:Docket.apiInfo()

   @Configuration
   // @EnableSwagger2WebFlux          //开启Swagger2WebFlux
   @EnableSwagger2WebMvc          //开启Swagger2WebMvc
   public class SwaggerConfig {
   
       /**
    	 * @ClassName SwaggerConfig
        * @Description     配置Swagger的Docket的bean实例
        * @Author admin
        * @Date 2020/7/6 20:54
        * @Version 1.0
        */
       @Bean
       public Docket docket(){
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo());
       }
   
       /**
    	 * @Author admin
        * @Description 配置Swagger信息
        * @Date 20:55 2020/7/6
        * @return
        **/
       private ApiInfo apiInfo(){
   
           // 作者信息
       Contact DEFAULT_CONTACT = new Contact("hanson", "http://localhost:8080", "邮箱");
           // 没有set方法,只能通过构造器设置值
           return new ApiInfo(
                   "Hello API文档",
                   "心有猛虎,细嗅蔷薇",
                   "V1.0",
                   "http://localhost:8080",
                   DEFAULT_CONTACT,
                   "Apache 2.0",
                   "http://www.apache.org/licenses/LICENSE-2.0",
                   new ArrayList<>());
       }
   }
   

   效果图:

   

2. 配置Swagger扫描接口:Docket.select()

   @Bean
   public Docket docket(){
       return new Docket(DocumentationType.SWAGGER_2)
           // 配置作者信息
           .apiInfo(apiInfo())
           //配置扫描接口
           .select()
           // RequestHandlerSelectors 配置扫描接口方式
               // basePackage 指定要扫描的包
               // any() 扫描全部
               // none() 都不扫描
               // withClassAnnotation() 扫描类上的注解,需要是一个注解的反射对象
               // withMethodAnnotation() 扫描方法上的注解
           .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
            // 路径过滤
               // ant() 过滤指定路径
               // any() 全部过滤
               // none() 都不过滤
               // regex() 正则匹配过滤
           .paths(PathSelectors.ant("*/service/*"))
           .build();
   }
   

3. 配置是否启动Swagger

   @Bean
   public Docket docket(){
       return new Docket(DocumentationType.SWAGGER_2)
           .apiInfo(apiInfo())
           //配置是否开启Swagger,true开启,false关闭
           .enable(true)
           .select()
           .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
           .build();
   }
   

配置API文档分组

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .enable(true)
        // 配置API文档分组
        .groupName("hanson")
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
        .build();
}

配置多个分组:配置多个Swagger的bean实例Docket

@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("hanson2");
}
@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("hanson3");
}
@Bean
public Docket docket4(){
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("hanson4");
}

实体类配置

// 1 在接口中返回值中存在实体类,就会扫描到swagger
@GetMapping(value = "/user")
public User usr(){
    return new User();
}
// 给实体类添加注解 @ApiModel("用户实体类")
// 也可以给字段添加注解 @ApiModelProperty("用户名")
@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    public String username;
    public int age;
}

给方法加注释:@ApiOperation(“用户方法注释”)

@ApiOperation("用户方法注释")
@GetMapping(value = "/user")
public User usr(){
    return new User();
}