工作中经常需要各种调试，前后端接口定义，测试人员测试，三方接入等实际场景中我们需要大量的输出API文档，既费时又费力。下面我将介绍一个开源工具Swagger UI，结合 spring boot 给大家讲解。
Swagger UI简介
Swagger UI 在没有任何实现逻辑的情况下可视化API的资源交互。它是根据OpenAPI（称为Swagger）规范自动生成的，可视化文档使后端实现和客户端使用变得容易。
image.png
第一步 环境配置
添加Swagger UI依赖
我们需要将Swagger UI的统一版本依赖加入到项目的pom.xml文件内，如下所示：
<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的Bean
package com.xiaoming.tools.commons.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
* @Description: swagger-ui 配置
* @Author: xiaoMing
* @Date: 2019/11/19 10:58
*/
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xiaoming.tools.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("这是标题")
.description("这里是一段描述，https://www.jianshu.com/u/85117e1faa39")
.termsOfServiceUrl("https://www.jianshu.com/u/85117e1faa39")
.version("1.0")
.build();
}
}
@Configuration会被项目启动加载为配置类,等同于XML中配置的beans；
@Bean标注方法等同于XML中配置的bean。
注：
basePackage的扫描路径是controller层
配置启动类
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SpringBootApplication
@EnableSwagger2
public class APP{
public static void main(String[] args) {
SpringApplication.run(APP.class, args);
}
}
在启动类上上注解@EnableSwagger2，代表开启swagger
第二步 使用
在controller上添加注解
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* @Description: swagger-ui demo
* @Author: xiaoming
* @Date: 2019/11/19 11:11
*/
@RestController
@RequestMapping(value = "/demo")
@Api(value = "demo")
public class DemoController {
@ApiOperation(value = "获取Model", notes = "根据实体id获取")
@PostMapping(value = "/getModel")
public Object getModel(@RequestBody ModelVO demo) {
return new ModelVO(1, 1);
}
}
@Api用于controller类上
@ApiOperation用在controller的方法上
在实体类上添加注解
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
* @Description: 实体对象
* @Author: xiaoming
* @Date: 2019/11/19 11:14
*/
@ApiModel(value = "ModelVO对象",description = "展示对象")
public class ModelVO {
@ApiModelProperty(value = "主键")
private Integer id;
@ApiModelProperty(value = "姓名",name = "id",required = true)
private String name;
@ApiModelProperty(value="状态：0启动，1停用",name="state",example="1")
private Integer state;
...
}
@ApiModel用在返回对象类上
-
value可为空 默认为class名 -
description可为空 默认''
@ApiModelProperty用在出入参数对象的字段上
-
value接收参数的意义描述 -
name接收参数名 -
required参数是否必填(true 必填，false 非必填) -
example举例说明
第三步 测试
启动项目访问 http://localhost:8080/swagger-ui.html
至此全部完毕
效果.png
本文首发于公众号「 晓明的30天实验室 」，关注公众号，即可获得更多相关教程。
如果你觉得文章还不错，请大家点赞分享下。你的肯定是我最大的鼓励和支持。
