springboot集成Swagger知识总结

Swagger简介
Swagger 是一套围绕 Open API 规范构建的开源工具，可以帮助设 计，构建，记录和使用 REST API。

Swagger 工具包括的组件：

Swagger Editor ：基于浏览器编辑器，可以在里面编写 Open API规范。类似 Markdown 具有实时预览描述文件的功能。

Swagger UI：将 Open API 规范呈现为交互式 API 文档。用可视化UI 展示描述文件。

Swagger Codegen：将 OpenAPI 规范生成为服务器存根和客户端 库。通过 Swagger Codegen 可以将描述文件生成 html 格式和 cwiki 形 式的接口文档，同时也可以生成多种言语的客户端和服务端代码。

Swagger Inspector：和 Swagger UI 有点类似，但是可以返回更多 信息，也会保存请求的实际参数数据。

Swagger Hub：集成了上面所有项目的各个功能，你可以以项目 和版本为单位，将你的描述文件上传到 Swagger Hub 中。在 Swagger Hub 中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

使用 Swagger，就是把相关的信息存储在它定义的描述文件里面（yml 或 json 格式），再通过维护这个描述文件可以去更新接口文档， 以及生成各端代码。
1.什么是swagger？
swagger是一组围绕openapi规范构建的开源工具，可以帮助设计构建、记录和使用REST API。

一、Springfox
　　使用 Swagger 时 如 果 碰 见 版 本 更 新或 迭 代 时 ， 只 需 要 更 改 Swagger 的描述文件即可。但是在频繁的更新项目版本时很多开发人 员认为即使修改描述文件（yml 或 json）也是一定的工作负担，久而 久之就直接修改代码，而不去修改描述文件了，这样基于描述文件生 成接口文档也失去了意义。

Marty Pitt 编写了一个基于 Spring 的组件 swagger-springmvc。 Spring-fox 就是根据这个组件发展而来的全新项目。

Spring-fox 是根据代码生成接口文档，所以正常的进行更新项目版本，修改代码即可，而不需要跟随修改描述文件。

Spring-fox 利用自身 AOP 特性，把 Swagger 集成进来，底层还是Swagger。但是使用起来确方便很多。 所以在实际开发中，都是直接使用 spring-fox。

Swagger集成Springboot
创建好maven
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.然后编写config包写SwaggerConfig类

package com.soldier.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**

• @Author soldier

• @Date 2020/3/11 11:42

• @Version 1.0

• @Description: Swagger配置
  */
  @Configuration
  public class SwaggerConfig {

  @Bean
  public Docket getDocket() {
  return new Docket(DocumentationType.SWAGGER_2)
  .apiInfo(swaggerDemoApiInfo())
  .select().build();
  }

  private ApiInfo swaggerDemoApiInfo() {
  return new ApiInfoBuilder()
  .contact(new Contact(“百度”, “www.baidu.com”, “baidu@163.com”))
  // 标题
  .title(“这是Swagger的标题”)
  // 描述
  .description(“这是Swagger的描述”)
  // 版本
  .version(“1.0.0”)
  .build();
  }
  }

3.运行重启项目，访问【http://localhost:8080/swagger-ui.html】，效果如下：
![在这里插入图片描述](https://img-blog.csdnimg.cn/20200713005648250.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM2ODE5ODMx,size_16,color_FFFFFF,t_70)
2、设置扫描的包

　　可以通过 apis()方法设置哪个包中内容被扫描
　　

@Bean
public Docket getDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(swaggerDemoApiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage(“com.soldier.controller”))
.build();
}

3、自定义注解设置不需要生成接口文档的方法

　　1）自定义注解，名称可以随便取

package com.soldier.interfaceDemo;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface NotIncludeSwagger {
}

2）添加规则

　　　　通 过 public ApiSelectorBuilder apis(Predicate<RequestHandler> selector)可以设置生成规则。

　　　　public static <T> Predicate<T> not(Predicate<T> predicate) :表示不 允许的条件。

　　　　withMethodAnnotation：表示此注解是方法级别注解。

@Bean
public Docket getDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(swaggerDemoApiInfo())
.select()
// .apis(RequestHandlerSelectors.basePackage(“com.soldier.controller”))
// 自定义注解设置不需要生成接口文档的方法
.apis(not(withMethodAnnotation(NotIncludeSwagger.class)))
.build();
}

3）添加 @NotIncludeSwagger 注解

　　　　在不需要生成接口文档的方法上面添加@NotIncludeSwagger 注 解后，该方法将不会被 Swagger 进行生成在接口文档中。

@NotIncludeSwagger
@RequestMapping("/getPeople2")
public People getPeople2(Long id, String name, String address) {
People people = new People();
people.setId(id);
people.setName(name);
people.setAddress(address);
return people;
}

**Swagger2 常用注解**
　　1）Api

　　@Api 是类上注解。控制整个类生成接口信息的内容。 tags：类的名称 可以有多个值 多个值表示多个副本，description:描述 已过时。
　　

@RestController
@RequestMapping("/people")
@Api(tags = {“myDemo”}, description = “DemoController描述”)
public class DemoController {

在swagger-ui.html 显示的效果：

![在这里插入图片描述](https://img-blog.csdnimg.cn/20200722174207152.png)
2）ApiOperation

　　@ApiOperation 写在方法上，对方法进行总体描述--》value：接口描述，notes：提示信息
　

@RequestMapping("/getPeople")
@ApiOperation(value = “接口描述”, notes = “提示信息”)

![在这里插入图片描述](https://img-blog.csdnimg.cn/2020072217423965.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM2ODE5ODMx,size_16,color_FFFFFF,t_70)
3）ApiParam

　　@ApiParam 写在方法参数前面。用于对参数进行描述或说明是否 为必添项等说明--》name：参数名称，value：参数描述，required：是否是必须
　　

@RequestMapping("/getPeople")
@ApiOperation(value = “接口描述”, notes = “提示信息”)
public People getPeople(Long id, @ApiParam(value = “姓名 这个是参数描述”, required = true) String name) {

4）ApiModel

　　@ApiModel 是类上注解，主要应用 Model，也就是说这个注解一 般都是写在实体类上--》value：名称，description：描述
　　

@ApiModel(value = “名称：人类”, description = “描述”)
public class People {

5）ApiModelProperty

　　@ApiModelProperty 可以用在方法或属性上。用于当对象作为参数时定义这个字段的内容--》value：描述，name：重写属性名，required：是否是必须的，example：示例内容，hidden：是否隐藏。
　　

@ApiModelProperty(value = “描述:姓名”, name = “重写属性名:name”, required = true, example = “张三”)
private String name;

6）ApiIgnore

　　@ApiIgnore 用于方法或类或参数上，表示这个方法或类被忽略。 和之前讲解的自定义注解@NotIncludeSwagger 效果类似。只是这个注 解是 Swagger 内置的注解，而@NotIncludeSwagger 是我们自定义的注解。

　　7）ApiImplicitParam

　　@ApiImplicitParam 用在方法上，表示单独的请求参数，总体功能 和@ApiParam 类似--》name：属性名，value：描述，required：是否是必须的，paramType：属性类型，dataType：数据类型
　　

@RequestMapping("/getPeople2")
@ApiImplicitParam(name = “address”,value = “地址”,required = true,paramType = “query”,dataType = “string”)
public People getPeople2(Long id, String name, String address) {

如果希望在方法上配置多个参数时，使用 @ApiImplicitParams 进行 配置。示例如下：

@RequestMapping("/getPeople2")
@ApiImplicitParams(value={
@ApiImplicitParam(name=“id”,value = “编号”,required = true),
@ApiImplicitParam(name=“name”,value = “姓名”,required = true)
})
public People getPeople2(Long id, String name, String address) {