swagger（API接口文档利器）

1、前言

接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变
成重中之重。接口文档固然重要,但是由于项目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接口文档和实际情况不一致。

很多人员会抱怨别人写的接口文档不规范，不及时更新。当时当自己写的时候确实最烦
去写接口文档。这种痛苦只有亲身经历才会牢记于心。如果接口文档可以实时动态生成就不会出现上面问题。

写文档也麻烦，那如果可以生成文档呢？Swagger就是做这个事。

Swagger是一个工具，我们使用其可以动态的生成前台和后台功能交互的API规范。

2、Swagger介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(https://swagger.io/)。 它的主要作用是：

1. 使得前后端分离开发更加方便，有利于团队协作
2. 接口的文档在线自动生成，降低后端开发人员编写接口文档的负担
3. 功能测试
   Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在项目中引入Springfox ，即可非常简单快捷的使用Swagger。

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中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

3、Springfox

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

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

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

Spring-fox利用自身AOP特性，把Swagger集成进来，底层还是Swagger。但是使用起来确方便很多。

所以在实际开发中，都是直接使用spring-fox。

4、Swagger常用注解

在Java类中添加Swagger的注解即可生成Swagger接口文档，常用Swagger注解如下：

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

  • tags:类的名称。可以有多个值，多个值表示多个副本。
  • description:描述，已过时。

• @ApiOperation：描述一个类的一个方法，或者说一个接口
  属性：

  • value:接口描述
  • notes:提示信息

• @ApiParam：单个参数的描述信息
  属性：

  • name:参数名称
  • value:参数描述
  • required:是否是必须

• @ApiModel：用对象来接收参数
  属性：

  • value:名称
  • description:描述

• @ApiModelProperty：用对象接收参数时，描述对象的一个字段
  属性：

  • value :描述
  • name: 重写属性名
  • required: 是否是必须的
  • example: 示例内容
  • hidden: 是否隐藏。

• @ApiResponse：HTTP响应其中1个描述

• @ApiResponses：HTTP响应整体描述

• @ApiIgnore：使用该注解忽略这个API

• @ApiError ：发生错误返回的信息

• @ApiImplicitParam：一个请求参数

• @ApiImplicitParams：多个请求参数的描述信息

• @ApiImplicitParam属性：
  

5、SpringBoot集成Swagger

5.1、引入springfox依赖

<dependency> 
	<groupId>io.springfoxgroupId> 
	<artifactId>springfox-swagger2artifactId> 
	<version>2.9.2version> 
dependency> 
<dependency> 
	<groupId>io.springfoxgroupId> 
	<artifactId>springfox-swagger-uiartifactId> 
	<version>2.9.2version> 
dependency>
1
2
3
4
5
6
7
8
9
10

5.2、在项目工程的application.propertis中配置swagger的启动开关

# 开启swagger 
swagger.enable=true
1
2

5.3、在项目工程的config包中添加一个配置类

package cn.bz.wanxinp2p.consumer.config;

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;

@Configuration
@ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true")
@EnableSwagger2  //开启swagger注解支持
public class SwaggerConfiguration {

	@Bean
	public Docket buildDocket() {
		/**
		 * Docket:摘要对象，通过对象配置描述文件的信息。
		 * apilnfo:设置描述文件中info。参数类型Apilnfoe'
		 * select():返回ApiSelectorBuilder对象，通过对象调用build()可以创建Docket对象
		 * ApilnfoBuilder: Apilnfo构建器。
		 */
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(buildApiInfo())
				.select()
				// 要扫描的API(Controller)基础包
				.apis(RequestHandlerSelectors.basePackage("cn.bz.wanxinp2p"))
				.paths(PathSelectors.any())
				.build();
	}

	private ApiInfo buildApiInfo() {
		Contact contact = new Contact("pzz","","");
		return new ApiInfoBuilder()
				//文档标题
				.title("P2P应用平台-用户服务API文档")   
				//文档描述  
				.description("包含用户服务api")
				.contact(contact)
				//文档版本
				.version("1.0.0").build();
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

5.4、在Controller中使用Swagger注解：

@RestController
@Api(value = "用户服务的Controller", tags = "Consumer", description = "用户服务API")
public class ConsumerController {

        @ApiOperation("测试hello")
        @GetMapping(path = "/hello")
        public String hello(){
            return "hello";
        }

        @ApiOperation("测试hi")
        @ApiImplicitParam(name="name",value="姓名",required = true,dataType = "String")
        @PostMapping(value = "/hi")
        public String hi(String name){
            return "hi,"+name;
        }

}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

5.5、生成文档（查看文档）

生成文档是一个HTML页面，需要访问查看。
项目路径 + swagger-ui.html

结束！！！！

---

									洗脸刷牙应该是每天都做的事情，无论你今天是否出门。
1