现在很多项目都是前后端分离模式,所以在开发团队中经常需要写 API 文档,便于前后端开发对接。
若手写 API 文档,则有以下几个痛点:
- 文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时。
- 文档编写需要单独占用时间,占用人力
- 接口文档太多,不好管理
- 不能直接在线测试接口,通常需要使用工具,比如 postman
SpringBoot 项目整合 swagger2 插件,可以快速生成接口文档,便于测试接口。当然 swagger2 也有缺点,最明显的就是代码移入性比较强。下面简单介绍下如何在项目中使用 swagger2。
一、在 pom.xml 里面添加 jar 依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
二、添加配置文件 Swagger2Config.java
package com.rabbit.producer.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Swagger2 插件配置
*
* @EnableSwagger2 表示开启Swagger
* @ConditionalOnProperty 这里的属性 key 是 swagger.enabled,havingValue 是期望值,只有在其值等于期望值的时候,才会生效。
* 也就是说,swagger.enabled 只能为 true 的时候才会生效,其他值或不设值,都不会生效的。
*/
@Configuration
@EnableSwagger2
@ConditionalOnProperty(prefix = "swagger", value = {"enabled"}, havingValue = "true")
public class Swagger2Config {
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SpringBoot整合RabbitMQ系统Restful API")
.description("SpringBoot整合RabbitMQ系统Restful API")
.version("1.0")
.build();
}
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 扫描的路径包
.apis(RequestHandlerSelectors.basePackage("com.rabbit.producer.controller"))
// 指定路径处理PathSelectors.any()代表所有的路径
.paths(PathSelectors.any()).build().pathMapping("/");
}
}
三、application.properties 配置文件中设置是否启用 swagger
server.port=8888
swagger.enabled=true
四、新建请求参数对象 EventMessage.java
package com.rabbit.common.entity;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import java.io.Serializable;
/**
* 消息类
*/
@Data
@NoArgsConstructor
@AllArgsConstructor
public class EventMessage implements Serializable {
private static final long serialVersionUID = -9203358002484642594L;
private String name;
private String desc;
}
五、新建测试类 TestContronller.java
package com.rabbit.producer.controller;
import com.rabbit.common.entity.EventMessage;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
/**
* 测试 swagger2 插件生成 restful 文档
*/
@RestController
@Slf4j
public class TestContronller {
@ApiOperation(value = "测试swagger2插件的使用", notes = "swagger2插件测试方法")
@ApiImplicitParam(name = "message", value = "消息类", required = true, dataType = "EventMessage")
@PostMapping("/testSwagger")
public String testSwagger(@RequestBody EventMessage message) {
log.info("desc:[{}];name:[{}]", message.getDesc(), message.getName());
return "HelloWorld";
}
}
六、启动项目并访问
启动项目并用浏览器访问路径:http://127.0.0.1:8888/swagger-ui.html,页面如下图所示。
- 红色方框:接口文档。单击即可打开查看。
- 绿色方框:接口请求参数 EventMessage。
- 蓝色方框:项目的测试方法列表。
具体接口测试步骤如下:
- 选择一个测试方法,单击绿色横条区域,点击右上角 Try it out 按钮。
- 按下图中顺序,依次编辑请求参数、单击Cancel、单击 Excute 按钮,即可完成测试。
测试返回应答数据如下图所示。
七、swagger2 注解说明
swagger2 通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息等。
@ApiOperation(value = “说明方法的用途、作用”, notes = “方法的备注说明”)(其他参数可参考源码)
@Api:修饰整个类,描述Controller的作用
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParam:用在 @ApiImplicitParams 注解中,指定一个请求参数的配置信息,用法示例:
@ApiImplicitParam(name = “参数名”, value = “参数的汉字说明、解释”, required = true, dataType = “参数类型,默认String,其它值自行填写”)
其中 required:参数是否必传,取值为 true or false。
@ApiImplicitParams:用于多个请求参数的方法,包含多个 @ApiImplicitParam,用法示例:
@ApiImplicitParams({
@ApiImplicitParam(name=“name”, value=“用户名”, dataType=“string”, paramType = “query”),
@ApiImplicitParam(name=“id”, value=“用户id”, dataType=“long”, paramType = “query”)
})