作为一个开发人员最怕的就是写文档了，但是要想成为一个合格的程序员，写好文档也是一个必备的技能。开发中我们经常要写接口服务，既然是服务就要跟别人对接，那难免要写接口文档，那么如何”优雅“的写接口文档呢？本文介绍一个在写代码的过程就可以写完接口文档的工具——Swagger2（江湖人称丝袜哥😂）
下文基于 SpringBoot + Maven 介绍 Swagger2 的使用
加入依赖
<!--Swagger-ui配置--> <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>复制代码编写Swagger全局配置
package com.ziyou.test.admin.config;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.ParameterBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.schema.ModelRef;import springfox.documentation.service.ApiInfo;import springfox.documentation.service.Parameter;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;import java.util.ArrayList;import java.util.List;/** * <br> * <b>功能：</b><br> * <b>作者：</b>@author 子悠<br> * <b>日期：</b>2019-03-28 23:35<br> * <b>详细说明：</b>Swagger配置类， * UI地址： http://127.0.0.1:8084/swagger-ui.html * JSON文档地址 http://127.0.0.1:8084/v2/api-docs * <br> */@EnableSwagger2@Configurationpublic class Swagger2Config { @Bean public Docket createRestApi() { //header中增加 token_id参数，没有可以去掉 ParameterBuilder token = new ParameterBuilder(); List<Parameter> pars = new ArrayList<Parameter>(); token.name("token_id").description("user token") .modelRef(new ModelRef("string")).parameterType("header") .required(false).build(); pars.add(token.build()); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() // 指定controller存放的目录路径 .apis(RequestHandlerSelectors.basePackage("com.ziyou.test.admin.controller")) .paths(PathSelectors.any()) .build() .globalOperationParameters(pars); } private ApiInfo apiInfo() { return new ApiInfoBuilder() // 文档标题 .title("这里是文档标题") // 文档描述 .description("这里是文档描述") .termsOfServiceUrl("这里可以增加需求文档 wiki 地址") .version("v1")//定义版本号 .build(); }}复制代码Controller 编写
•类上面增加@Api注解
@Api(value = "后台管理", tags = "Administrator - 后台主入口")public class MainController {}复制代码•方法上增加@ApiOperation注解
@ApiOperation(value = "用户登录——可用", httpMethod = "POST", response = ResultMsg.class) public ResultMsg login(@RequestBody LoginBean loginBean) throws Exception {}//value: 表示描述//httpMethod: 支持的请求方式// response: 返回的自定义的实体类复制代码•方法参数 Model 属性自定义设置
package com.ziyou.test.admin.bean;import io.swagger.annotations.ApiModel;import io.swagger.annotations.ApiModelProperty;import java.util.Date;@ApiModel(value = "用户对象", description = "用户对象model")public class LoginBean { @ApiModelProperty(value = "用户登录账户", name = "loginName", required = true, example = "admin") private String loginName;// 账号 @ApiModelProperty(value = "用户登录密码", name = "loginPwd", required = true, example = "123456") private String loginPwd;// 密码 @ApiModelProperty(hidden = true) private String salt;// 盐值 public String getLoginName() { return this.loginName; } public void setLoginName(String loginName) { this.loginName=loginName; } public String getLoginPwd() { return this.loginPwd; } public void setLoginPwd(String loginPwd) { this.loginPwd=loginPwd; } public String getSalt() { return this.salt; } public void setSalt(String salt) { this.salt=salt; }}复制代码@ApiModel注解用在 model 类上 @ApiModelProperty 用于 model 的属性上
•可以定义是否 required, example, hidden, value, name等参数•hidden 为 true 在页面上就不会显示在字段
界面使用
•
启动项目，打开项目文档地址：http://ip:port/swagger-ui.html[1
•
如图显示的内容。还可以添加 header 参数，以及在网页上进行测试
增加密码
•接口文档我们往往需要让有权限的人查看，所以我们可以根据 Spring-Security增加账号密码管理。•增加依赖
<!--Swagger-ui 密码配置配置--><dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId></dependency>复制代码•配置文件中增加账号密码配置
Spring: security: basic: path: /swagger-ui.html enabled: true user: name: admin password: 123456# swagger-ui.html账号密码配置信息，根据版本不同，可能需要如下方式#security.basic.path=/swagger-ui.html#security.basic.enabled=true#security.user.name=admin#security.user.password=123456复制代码•增加了依赖和账号密码后重启项目，再次打开文档地址就要去输入账号和密码输入对应的账号和密码就可以登录了。
小坑
•如果在启动的时候出现如下错误，是因为新版的 Swagger2需要高版本的 guava
***************************APPLICATION FAILED TO START***************************Description:An attempt was made to call the method com.google.common.collect.FluentIterable.concat(Ljava/lang/Iterable;Ljava/lang/Iterable;)Lcom/google/common/collect/FluentIterable; but it does not exist. Its class, com.google.common.collect.FluentIterable, is available from the following locations: jar:file:/Users/silence/Work/maven-repo3/com/google/guava/guava/19.0/guava-19.0.jar!/com/google/common/collect/FluentIterable.classIt was loaded from the following location: file:/Users/silence/Work/maven-repo3/com/google/guava/guava/19.0/guava-19.0.jarAction:Correct the classpath of your application so that it contains a single, compatible version of com.google.common.collect.FluentIterable复制代码•解决方案增加如下配置即可
<dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>20.0</version></dependency>复制代码•
Security 过滤特定路径
•针对非文档路径的其他路径，我们需要进行过滤，采用如下方式。
/** * 取消 security 对接口的拦截，只在 swaggerui 进行拦截 * * @param web * @throws Exception */@Overridepublic void configure(WebSecurity web) throws Exception { super.configure(web); //这里填写需要过滤的路径 web.ignoring().antMatchers("/api/v1/admin/**");}复制代码}
小结
Swagger2 让开发人员在编写代码的时候就完成了接口文档，方便快捷。而且随项目一起部署，不用担心丢失，需要的时候只要打开项目地址就可以了，十分方便。
在使用 Swagger2写完接口文档后，还可以直接导出 JSON 文件，访问路径`http://ip:port/v2/api-docs`可以看到JSON 文档。生成的 JSON 文档可以配合 YAPI 或者 POSTMAN 使用都是可以的。
Java 极客技术公众号，是由一群热爱 Java 开发的技术人组建成立，专注分享原创、高质量的 Java 文章。如果您觉得我们的文章还不错，请帮忙赞赏、在看、转发支持，鼓励我们分享出更好的文章。
关注公众号，大家可以在公众号后台回复“掘金”，获得作者 Java 知识体系/面试必看资料。