1、前言
接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变
成重中之重。接口文档固然重要,但是由于项目周期等原因后端人员经常出现无法及时更新,导致前端人员抱怨接口文档和实际情况不一致。
很多人员会抱怨别人写的接口文档不规范,不及时更新。当时当自己写的时候确实最烦
去写接口文档。这种痛苦只有亲身经历才会牢记于心。如果接口文档可以实时动态生成就不会出现上面问题。
写文档也麻烦,那如果可以生成文档呢?Swagger就是做这个事。
Swagger是一个工具,我们使用其可以动态的生成前台和后台功能交互的API规范。
2、Swagger介绍
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(https://swagger.io/)。 它的主要作用是:
- 使得前后端分离开发更加方便,有利于团队协作
- 接口的文档在线自动生成,降低后端开发人员编写接口文档的负担
- 功能测试
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.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>
5.2、在项目工程的application.propertis中配置swagger的启动开关
# 开启swagger
swagger.enable=true
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();
}
}
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;
}
}
5.5、生成文档(查看文档)
生成文档是一个HTML页面,需要访问查看。
项目路径 + swagger-ui.html
结束!!!!
洗脸刷牙应该是每天都做的事情,无论你今天是否出门。