一、Swagger介绍
Swagger是一个开源文档生成器，可以方便的用来生成OpenAPI规格的接口文档，支持Go、Python、Haskell、Java等多种语言，同时支持在线调试接口。
官网：
https://swagger.io
Swagger 工具集包含：
? Swagger Editor – 在线编写 OpenAPI 规范的编辑器
? Swagger UI – 使用 OpenAPI 规范生成的交互式文档
? Swagger Codegen – 使用 OpenAPI 规范分别生成客户端/服务器代码（Server-stub）的工具
同类型的工具还有：
- docway
附：OpenAPI 中文文档：https://fishead.gitbooks.io/openapi-specification-zhcn-translation/content/versions/3.0.0.zhCN.html#oasDocument
二、java下的使用
1. 加入依赖
在Springboot环境下的使用十分简单，只需要加入依赖：
<!-- swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>2. 书写SwaggerConfig文件
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket ProductApi() {
return new Docket(DocumentationType.SWAGGER_2)
.genericModelSubstitutes(DeferredResult.class)
.useDefaultResponseMessages(false)
.forCodeGeneration(false)
.pathMapping("/")
.select()
.build()
.apiInfo(productApiInfo());
}
private ApiInfo productApiInfo() {
ApiInfo apiInfo = new ApiInfo("XXX系统数据接口文档",
"文档描述。。。",
"1.0.0",
"API TERMS URL",
"联系人邮箱",
"license",
"license url");
return apiInfo;
}
}启动Springboot项目后，就可以通过 http://localhost:8080/swagger-ui.html：
来访问接口：
3. 接口注解
2.3.1 controller上的注解
@Api(value="用户controller",tags={"用户操作接口"})
@Controller
@RequestMapping("web/user")
public class UserController {
}2.3.2 方法上的注解
@GetMapping("/userInfo")
@ResponseBody
@ApiOperation(value = "查询个人信息", tags = {"返回用户信息"}, notes = "提交json格式")
public Result userInfo(@ApiParam(name="phone",value="用户手机号",required=true)String phone) {
Result result = new Result();
return result;
}2.3.3 实体类上的注解
@ApiModel(description="登录请求参数")
public class UserLoginDto {
@ApiModelProperty(value="用户电话", required=true)
private String phone;
@ApiModelProperty(value="密码", required=true)
private String password;
public String getPhone() {
return phone;
}
public void setPhone(String phone) {
this.phone = phone;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
}2.3.4 常用注解说明
- @Api() 用于类，表示swagger的注解资源
- @ApiOperation() 用于方法，表示一个http请求
- @ApiParam()，用于方法的参数，说明字段使用
- @ApiModel()，于用实体类
- @ApiIgnore 用于类、方法、方法参数，表示这个方法或类被忽略
- @ApiImplicitParam() 用于方法，表示单独的请求参数
- @ApiImplicitParams()用于方法，包含多个 @ApiImplicitParam
- @ApiResponses() 用于方法，包含多个 @ApiResponse
三、更换前端UI
默认的swagger-ui不怎么符合国人的审美观。好在有一些好心的开发者提供了更漂亮的API界面，下面简单介绍几款：
1. knife4j
为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui。使用该工具还可以方便的生成md格式接口源文件。
其功能比较多，只更换swagger-ui的话引用：
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-ui</artifactId>
<version>${lastVersion}</version>
</dependency>或者使用老版本：
<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.1</version>
</dependency>界面效果：
2. Swagger-UI-layer
地址： https://gitee.com/caspar-chen/Swagger-UI-layer
引用：
<dependency>
<groupId>com.github.caspar-chen</groupId>
<artifactId>swagger-ui-layer</artifactId>
<version>${last-version}</version>
</dependency>效果：
doc访问地址： http://****/docs.html
3. tennetcn
引用：
<dependency>
<groupId>com.tennetcn.free</groupId>
<artifactId>think-swagger-ui-starter</artifactId>
<version>0.0.4</version>
</dependency>效果：
4. swagger-mg-ui
引用：
<!-- https://mvnrepository.com/artifact/com.zyplayer/swagger-mg-ui -->
<dependency>
<groupId>com.zyplayer</groupId>
<artifactId>swagger-mg-ui</artifactId>
<version>1.0.6</version>
</dependency>效果：
5. swagger-document-ui
引用：
移除官方 UI 依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${springfox.version}</version>
</dependency>添加 swagger-document-ui 依赖
<dependency>
<groupId>cn.javaer.springfox</groupId>
<artifactId>swagger-document-ui</artifactId>
<version>1.0.2</version>
</dependency>开源地址：https://gitee.com/cn-src/swagger-document-ui
效果：