作为一个开发人员最怕的就是写文档了，但是要想成为一个合格的程序员，写好文档也是一个必备的技能。开发中我们经常要写接口服务，既然是服务就要跟别人对接，那难免要写接口文档，那么如何”优雅“的写接口文档呢？本文介绍一个在写代码的过程就可以写完接口文档的工具——Swagger2
文基于 SpringBoot + Maven 介绍 Swagger2 的使用
加入依赖
[Java] 纯文本查看 复制代码 <!--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全局配置
[Java] 纯文本查看 复制代码 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地址： [url=http://127.0.0.1:8084/swagger-ui.html]http://127.0.0.1:8084/swagger-ui.html[/url]
* JSON文档地址 [url=http://127.0.0.1:8084/v2/api-docs]http://127.0.0.1:8084/v2/api-docs[/url]
* <br>
*/
@EnableSwagger2
@Configuration
public 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 注解
[Java] 纯文本查看 复制代码 @Api(value = "后台管理", tags = "Administrator - 后台主入口")
public class MainController {}
方法上增加@ApiOperation注解
[Java] 纯文本查看 复制代码 @ApiOperation(value = "用户登录——可用", httpMethod = "POST", response = ResultMsg.class)
public ResultMsg login(@RequestBody LoginBean loginBean) throws Exception {}
//value: 表示描述
//httpMethod: 支持的请求方式
// response: 返回的自定义的实体类
方法参数 Model 属性自定义设置
[Java] 纯文本查看 复制代码 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
如图显示的内容。还可以添加 header 参数，以及在网页上进行测试。
增加密码- 接口文档我们往往需要让有权限的人查看，所以我们可以根据 Spring-Security增加账号密码管理。
- 增加依赖
[Java] 纯文本查看 复制代码
<!--Swagger-ui 密码配置配置-->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>- 配置文件中增加账号密码配置
[Java] 纯文本查看 复制代码 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- 增加了依赖和账号密码后重启项目，再次打开文档地址就要去输入账号和密码了
-
- 输入对应的账号和密码就可以登录了。
转载：http://www.justdojava.com/2019/03/28/java-swagger/# | 
收藏
淘帖
踩
