书写和前端对接的api文档十分痛苦，工作中经常会有下面场景
- 接口文档地址分散
- 接口文档相对代码更新滞后
- 前端同事找不到对接的后端同事
- 懒得写
- 其他
swagger框架很好的解决其中的一些问题。
先上效果
这里出现了一个类似接口文档的web界面，里面有文档的title
xx系统接口文档
文档的描述
swagger 接口测试
以及一些作者信息
image.png
点开
demo-controller:接口测试
可以看到一个接口
GET /test/person
还有一个类似postman的界面。里面有request的parameter的描述，response结构的描述。
image.png
我们随便输入一个name的value，然后try it out
image.png
出现了这个请求的response
{
"code": "000",
"msg": "success",
"data": {
"name": "鸡熟了",
"age": 29
}
}
这样，一个非常简单的接口调试就完成了。
下面我们看看代码是怎么实现的。
首先新建一个springboot 的web应用
然后引入swagger的maven依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
配置swagger
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Configuration
public class SwaggerDocket {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// .pathMapping("/")
.select() // 选择那些路径和api会生成document
// .apis(RequestHandlerSelectors.any())// 对所有api进行监控
//不显示错误的接口地址
.paths(Predicates.not(PathSelectors.regex("/error.*")))//错误路径不监控
.paths(PathSelectors.any())// 对根下所有路径进行监控
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("xx系统接口文档")
.contact(new Contact("鸡熟了", "http://xxx.blog.com", "xxx@gmail.com"))
.description("swagger 接口测试")
.termsOfServiceUrl("NO terms of service")
.license("The Apache License, Version 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
.version("v1.0")
.build();
}
}
}
随便定义几个对象
@Data
@ApiModel("通用response")
public class DemoResp<T> {
@ApiModelProperty("返回code")
private String code;
@ApiModelProperty("返回msg")
private String msg;
@ApiModelProperty("返回data")
private T data;
public static <T> DemoResp<T> success(T data) {
DemoResp<T> resl = new DemoResp<>();
resl.setCode("000");
resl.setMsg("success");
resl.setData(data);
return resl;
}
}
@Data
@Builder
@ApiModel("人")
public class Person {
@ApiModelProperty("名字")
private String name;
@ApiModelProperty("年龄")
private Integer age;
}
随便写一个REST接口的controller
@RestController
@RequestMapping("/test")
@Api(description = "测试接口")
public class DemoController {
@GetMapping("/person")
@ApiOperation("根据用户名获取用户信息")
public DemoResp<Person> getPerson(@RequestParam("name") @ApiParam("名字") String name) {
return DemoResp.success(Person.builder().name("鸡熟了").age(29).build());
}
}
D大的网友已经发现，文档里面对应的信息，全是用注解的方式，书写在
- controller类
- 方法
- 对象
上面，所有用注解标注的都会在文档页面显示。
默认swagger生成的文档web地址：
swagger文档会随着应用一起启动。
这样，只需要把这个url发给前端同事就行了。当接口有变更的时候，修改对应的注解，应用启动之后就会自动生效。
当然swagger还有更详细，更丰富的玩法。可以自行研究。
完
