曾经我们使用的接口文档,都是基于word格式,缺点太明显。文档每次更新需要手动发送给前端开发者,更新交流不及时、不能在线直接测试,可能存在多个模块的文档,不便管理。写接口文档描述也花时间,前端开发者看着文档也累、、、
so,我们team自己开发了一套接口文档插件,基于注解形式自动生成html文档。哇,不用写文档了,真tm开心,哈哈。
直到某年某月的某一天,发现了swagger这样的神器。比我们做的更大而全,也是开源项目,懒人开发的福音。
直接开始!pom中引入依赖:
<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>
在项目中添加Swagger配置类:
package org.jc.demo.config;
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;
/**
* Swagger 配置类<br/>
* Author:杨杰超<br/>
* Date:2018年6月18日 下午11:26:51 <br/>
* Copyright (c) 2018, yangjiechao@dingtalk.com All Rights Reserved.<br/>
*
*/
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
// 创建API基本信息
return new Docket(DocumentationType.SWAGGER_2)
// 选择那些路径和api会生成document
.apiInfo(apiInfo()).select()
// 扫描该包下的所有需要在Swagger中展示的API,@ApiIgnore注解标注的除外
.apis(RequestHandlerSelectors.basePackage("org.jc.demo.controller"))
对所有api进行监控
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
// 创建API的基本信息,这些信息会在Swagger UI中进行显示
return new ApiInfoBuilder()
// API标题
.title("测试文档神器Swagger APIs")
// API描述
.description("这里是描述信息")
// 版本号
.version("1.0").build();
}
}
Docket、ApiInfoBuilder对象具体参数请查阅源码与相关资料,这里只提供最简单的实现。
然后添加Controller
@RestController
@Api(tags = "grab-service", description = "抓取服务相关接口")
public class TestController {
@Autowired
private TestService service;
// 使用该注解描述接口方法信息
@ApiOperation(value = "接口名称", notes = "接口的描述信息")
@ApiImplicitParams(
{@ApiImplicitParam(name = "name", value = "名称", required = true, dataType = "String", paramType = "path")}
)
@RequestMapping(value = "/test/{name}", method = RequestMethod.GET)
public String test(@PathVariable String name) {
return service.test(name);
}
常用注解:
@Api()用于类; 表示标识这个类是swagger的资源
@ApiOperation()用于方法; 表示一个http请求的操作
@ApiParam()用于方法,参数,字段说明; 表示对参数的添加元数据(说明或是否必填等)
@ApiModel()用于类 表示对类进行说明,用于参数用实体类接收
@ApiModelProperty()用于方法,字段 表示对model属性的说明或者数据操作更改
@ApiIgnore()用于类,方法,方法参数 表示这个方法或者类被忽略
@ApiImplicitParam() 用于方法 表示单独的请求参数
@ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam
权威指南:github项目主页
就这样就可以在项目中直接使用Swagger生成接口文档了,
启动项目,直接访问:http://localhost:port/swagger-ui.html 查看效果吧。
我们在项目中很少这样用,感觉需要设置的东西太多了,精简了一些参数。效果如下:
@RestController
@RequestMapping(value = "/order", produces = "application/json")
@Api(description = "订单服务接口", tags = "api-order")
public class OrderController extends AbstractController {
@Autowired
private OrderService orderService;
@ApiOperation(value = "订单支付", notes = "订单支付")
@ApiResponses({
@ApiResponse(code = 601, message = "请求参数错误"),
@ApiResponse(code = 602, message = "系统未知异常")
//
})
@RequestMapping(value = "/order/pay", method = {RequestMethod.POST})
public BaseRespDto orderPay(@RequestBody OrderPayReqDto req) {
return orderService.orderPay(req);
}
}
参数详细注解在参数类中实现
BaseRespDto:
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@Data
public class BaseRespDto {
@ApiModelProperty(notes = "结果描述")
private String respMsg = "成功";
}
OrderPayReqDto:
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@Data
@ApiModel("订单支付请求实体")
public class OrderPayReqDto extends BaseReqDto {
@ApiModelProperty(notes = "订单ID")
private Long orderId;
// 省略其他参数
}
Swagger2 GitHub :
https://github.com/swagger-api/swagger-core