目录
3.接口文档测试地址
Swagger2
一、简介
一般我们在对接前后端的时候,都需要提供相应的接口文档。对于后端来说,编写接口文档即费时费力,还会经常因为没有及时更新,导致前端对接时出现实际接口与文档不一致。而且手写接口文档还容易出错,而swagger很好的解决了这个痛点。
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。可用于:1.接口的文档在线自动生成、2.功能测试。
二、使用
1.maven导入Swagger
目前企业用的最多的版本还是2.x,这里推荐使用
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
2.创建Swagger2配置类
这个配置类复制过去改改就好了~
实际开发中,我们可能针对不同的开发人员或者开发模块,单独分组设置api接口文档。
如下就对应了三种接口文档~
如果你嫌麻烦,也可以只用一组~
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket webAllConfig(){
return new Docket(DocumentationType.SWAGGER_2)
// 组名
.groupName("webAllApi")
.apiInfo(webAllInfo())
.select()
//显示当前所有接口
.paths(PathSelectors.any())
// 不显示/error下的接口(swagger自带的)
.paths(Predicates.not(PathSelectors.regex("/error.*")))
.build();
}
private ApiInfo webAllInfo(){
return new ApiInfoBuilder()
.title("天猫猫商城-所有文档")
.description("本文档描述了网站微服务接口定义")
.version("1.0")
.contact(new Contact("hssy", "https://www.baidu.com", "123456@qq.com"))
.build();
}
@Bean
public Docket frontApiConfig(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("frontApi")
.apiInfo(frontApiInfo())
.select()
//只显示api路径下的页面
.paths(Predicates.and(PathSelectors.regex("/api/.*")))
.build();
}
private ApiInfo frontApiInfo(){
return new ApiInfoBuilder()
.title("前台网站-API文档")
.description("本文档描述了网站微服务接口定义")
.version("1.0")
.contact(new Contact("hssy", "https://www.baidu.com", "123456@qq.com"))
.build();
}
@Bean
public Docket adminApiConfig(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("adminApi")
.apiInfo(adminApiInfo())
.select()
//只显示admin路径下的页面
.paths(Predicates.and(PathSelectors.regex("/admin/.*")))
.build();
}
private ApiInfo adminApiInfo(){
return new ApiInfoBuilder()
.title("后台管理系统-API文档")
.description("本文档描述了后台管理系统微服务接口定义")
.version("1.0")
.contact(new Contact("hssy", "https://www.baidu.com", "123456@qq.com"))
.build();
}
}
3.接口文档测试地址
ip:port/swagger-ui.html
4.常用注解说明
先记住以下四个最常用的~
@Api : 用在类上,用来指定接口的描述文字
@RestController @RequestMapping("/newcustomer/industry") @Api(tags = "行业标签接口") public class IndustryController { @Autowired private IndustryService industryService;
@ApiOperation:用在方法上,用来对接口中具体方法做描述
value
:对接口的总体描述
notes
:对接口的详细描述
httpMethod
:请求方式,必须要和@RequestMapping保持一致@GetMapping("/findAll") @ApiOperation(value = "查询所有行业标签",notes = "查询所有行业标签,这里是详细描述信息!",httpMethod = "GET") public Result<List<Industry>> findAll(){ return industryService.findAll(); }
@ApiModel:作用在类上,用来描述一个实体类信息
value
:类名
description
:实体类描述@ApiModel(value = "Industry对象", description = "行业标签") public class Industry implements Serializable { private static final long serialVersionUID = 1L; @ApiModelProperty("主键id") @TableId(value = "id", type = IdType.AUTO) private Integer id;
@ApiModelProperty:作用在类的属性上,用来描述一个实体类的属性
value
:默认属性,类属性描述@ApiModelProperty("标签名称") @TableField("name") private String name;
或者
@ApiModelProperty(value = "标签名称") @TableField("name") private String name;
补充:
更好看的ui风格
这里再推荐一种更好看的ui界面,只需要引入另外一个jar包。
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.3</version>
</dependency>
当然了,它和原来的springfox-swagger-ui依赖并不冲突,你也可以不要原来的ui,就不用导入springfox-swagger-ui这个依赖,直接替换就可以了。
然后我们启动项目,只需访问ip:port/swagger-ui.html即可。