简介：

openAPI

Springfox：

简介

Springfox的使用

SwaggerUI的使用

Swagger配置

设置扫描的包

设置范围

Swagger常用注解：

控制类、方法生成接口信息

@ApiParam

@ApiModel

@ApiModelProperty

@ApiIgnore

@ApiImplicitParam

部分图片来自百战程序员

简介：

接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要，但是由于项目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接口文档和实际情况不一致。很多人员会抱怨别人写的接口文档不规范，不及时更新。如果接口文档可以实时动态生成就不会出现上面问题，Swagger可以完美地解决上面的问题。Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful 风格的 Web 服务，可用于接口的文档在线自动生成以及功能测试。

openAPI

Open API 是什么：Open API 规范(OpenAPI Specification)以前叫做 Swagger 规范，是REST API 的 API 描述格式。Open API 文件允许描述整个 API，包括：

每个访问地址的类型。POST 或 GET
每个操作的参数。包括输入输出参数
认证方法
连接信息，声明，使用团队和其他信息。

Open API 规范可以使用YAML或 JSON格式进行编写，这样更利于我们和机器进行阅读。

Swagger和Open API

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 中。在 SwaggerHub 中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。使用 Swagger，就是把相关的信息存储在它定义的描述文件里面（yml 或 json 格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码

Springfox：

简介

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

由于Spring的流行，Marty Pitt 编写了一个基于Spring 的组件swagger-springmvc。Spring-fox 就是根据这个组件发展而来的全新项目。Spring-fox 是根据代码生成接口文档，所以正常的进行更新项目版本，修改代码即可，而不需要跟随修改描述文件。Spring-fox 利用自身 AOP 特性，把 Swagger 集成进来，底层还是Swagger。但是使用起来确方便很多。所以在实际开发中，都是直接使用 spring-fox。官网地址：

GitHub - springfox/springfox: Automated JSON API documentation for API's built with Spring

Springfox的使用

1、创建SpringBoot项目，添加spring-fox依赖

在项目的pom.xml中导入Spring-fox依赖。选择版本2.9.2，所以导入的依赖也是这个版本。其中 springfox-swagger2 是核心内容的封装。springfox-swagger-ui 是对 swagger-ui 的封装。

<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、创建实体类

public class People {
    private int id;
    private String name;
    private String address;

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }
}

3、创建controller

@RestController
@RequestMapping("/people")
public class MyController {

    @RequestMapping("/getPeople")
    public People getPeople(int id,String name){
        People people = new People();
        people.setId(id);
        people.setName(name);
        people.setAddress("深圳");
        return people;
    }
}

4、在启动类中添加@EnableSwagger2注解，添加此注解后表示对当前项目中全部控制器进行扫描，应用Swagger2。

@SpringBootApplication
@EnableSwagger2
public class SwaggerBlogApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerBlogApplication.class, args);
    }

}

访问 swagger-ui

启动项目后在浏览器中输入 http://IP:port/swagger-ui.html即可以访问到 swagger-ui 页面，在页面中可以可视化的进行操作项目中所有接口。

SwaggerUI的使用

访问 swagger-ui.html 可以在页面中看到所有需要生成接口文档的控制器名称。

每个控制器包含该控制器下所有的方法及访问方式。如果使用的是@RequestMapping 进行映射，将显示下面的所有请求方式。如果使用@PostMapping 将只有 Post 方式可以能访问，下面也就只显示Post 的一个。

点击某个请求方式中 try it out

输入参数值，完成后点击 Execute 按钮

下面会出现 Request URL 以及响应结果。

Swagger配置

可以在项目中创建 SwaggerConfig，进行配置文档内容

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

    private ApiInfoswaggerDemoApiInfo(){
        return new ApiInfoBuilder()
       .contact(new Contact("北京尚学堂",           "http://www.bjsxt.com","xxx@163.com"))
    //文档标题
     .title("这里是Swagger的标题")
    //文档描述
     .description("这里是Swagger的描述")
    //文档版本
     .version("1.0.0")
     .build();
    }
}

配置基本信息

配置项	含义
Docket	摘要对象，通过对象配置描述文件的信息。
apiInfo	设置描述文件中 info，参数类型 ApiInfo
select()	返回 ApiSelectorBuilder 对象，通过对象调用 build()可以创建 Docket 对象
ApiInfoBuilder	ApiInfo 构建器

显示效果如下：

设置扫描的包

设置扫描的包

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

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

设置范围

通过下面的代码

public ApiSelectorBuilder paths(Predicate<String> selector)

可以设置满足什么样规则的 url 被生成接口文档。可以使用正则表达式进行匹配。

下面例子中表示只有以/demo/开头的 url 才能被 swagger 生成接口文档。

@Bean
public Docket getDocket(){
    return new Docket(DocumentationType. SWAGGER_2)
     .apiInfo(swaggerDemoApiInfo())
     .select()
     .paths(allowPaths())
     .build();
}
private Predicate<String> allowPaths(){
  return or(regex("/demo/.*"));
}

如何希望全部扫描可以使用
paths(PathSelectors.any())

Swagger常用注解：

控制类、方法生成接口信息

@Api

注解名称	参数	含义
@Api		类上注解。控制整个类生成接口信息的内容
	tags	类的名称，可以有多个值，多个值表示多个副本
	description	描述

代码示例如下：

@RestController
@RequestMapping("/people")
@Api(tags = "TestApi",description = "描述")
public class MyController {

    @PostMapping("/getPeople")
    public People getPeople(int id,String name){
        People people = new People();
        people.setId(id);
        people.setName(name);
        people.setAddress("深圳");
        return people;
    }
}

在 swagger-ui.html 中显示效果

@ApiOperation

注解名称	参数	含义
@ApiOperation		写在方法上，对方法进行总体描述
	value	接口描述
	notes	提示信息

代码示例：

@RestController
@RequestMapping("/people")
@Api(tags = "TestApi",description = "描述")
public class MyController {

    @ApiOperation(value = "获取人类",notes = "获取人类的信息")
    @PostMapping("/getPeople")
    public People getPeople(int id,String name){
        People people = new People();
        people.setId(id);
        people.setName(name);
        people.setAddress("深圳");
        return people;
    }
}

在 swagger-ui 中显示效果

@ApiParam

ApiParam

注解名称	参数	含义
@ApiParam		写在控制器方法参数前面。用于对参数进行描述或说明是否为必添项等说明
	name	参数名称
	value	参数描述
	required	是否是必须

在代码中示例：

@RestController
@RequestMapping("/people")
@Api(tags = "TestApi",description = "描述")
public class MyController {

    @ApiOperation(value = "获取人类",notes = "获取人类的信息")
    @PostMapping("/getPeople")
    public People getPeople(int id,@ApiParam(value = "姓名",required = true) String name){
        People people = new People();
        people.setId(id);
        people.setName(name);
        people.setAddress("深圳");
        return people;
    }
}

swagger-ui 显示效果如下：

@ApiModel

ApiModel

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

代码示例：

@ApiModel(value = "人类",description = "描述")
public class People {......}

swagger-ui.html 效果展示

@ApiModelProperty

注解名称	参数	含义
@ApiModelProperty		一般用于实体类方法、属性的说明
	value	字段说明
	name	重写属性名
	required	是否必须
	example	示例内容
	hidden	是否隐藏

代码示例：

@ApiModel(value = "人类",description = "描述")
public class People {
    private int id;
    @ApiModelProperty(value = "姓名",required = true,example = "张三")
    private String name;
    private String address;
    ......

}

@ApiIgnore

注解名称	含义
@ApiIgnore	用于方法或类或参数上，表示这个方法或类被忽略

@RestController
@RequestMapping("/people")
@Api(tags = "TestApi",description = "描述")
@ApiIgnore
public class MyController {

    @ApiOperation(value = "获取人类",notes = "获取人类的信息")
    @PostMapping("/getPeople")
    public People getPeople(int id,@ApiParam(value = "姓名",required = true) String name){
        People people = new People();
        people.setId(id);
        people.setName(name);
        people.setAddress("深圳");
        return people;
    }
}

@ApiImplicitParam

注解名称	参数	含义
@ApiImplicitParam		用在控制器方法上，表示单独的请求参数，总体功能和@ApiParam 类似。
	value	对接口中的参数进行简单必要的描述
	name	描述接口中参数的名称
	required	是否必须
	paramType	接口中的参数应该用在哪个地方，常用的位置有：header、query 、path
	dataType	接口中参数的类型

代码示例：

@RestController
@RequestMapping("/people")
@Api(tags = "TestApi",description = "描述")
//@ApiIgnore
public class MyController {

    @ApiOperation(value = "获取人类",notes = "获取人类的信息")
    @PostMapping("/getPeople")
    @ApiImplicitParam(value = "编号",name = "id")
    public People getPeople(int id, @ApiParam(value = "姓名",required = true) String name){
        People people = new People();
        people.setId(id);
        people.setName(name);
        people.setAddress("深圳");
        return people;
    }
}

swagger-ui.html 效果展示