## Swagger UI 简单使用
> [Springfox](http://springfox.github.io/springfox/ "Springfox") ： SpringBoot下[swagger](https://swagger.io/ "swagger") UI的简单的介绍以及使用
### 介绍
在SpringBoot下使用Swagger可以快速生成API相关信息并页面展示，便于API测试及生成API文档，下面是一段Swagger的介绍：
> swagger是一个流行的API开发框架，框架以“开放API声明”（OpenAPI Specification，OAS）为基础，对整个API的开发周期都提供了相应的解决方案。OAS本身是一个API规范，用于描述一整套API接口信息，在设计的时候通常是YAML格式，这种格式书写起来比较方便，而在网络中传输时又会以json形式居多。
> swagger-springmvc是一个基于Spring的组件，用于将swagger集成到springmvc中来。而springfox则是从这个组件发展而来，springfox-swagger2这个组件帮助我们自动生成OSA描述json文件，另外一个组件springfox-swagger-ui就是将这个json文件解析出来，用一种更友好的方式呈现出来。
### 引入依赖
基于gradle创建一个简单的sprinboot项目，并以此说明下springfox的简单使用。
```groovy
//springfox使用2.9.2版本
compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
```
### Swagger2初始化配置
SwaggerConfig.java类来初始化一些Swagger相关配置：主要是需要提供一个Docket实例，该实例用来配置Swagger2需要扫描API的包，请求路径，以及其他API描述信息
```java
@Configuration
@EnableSwagger2 //启用EnableSwagger2自动化配置
public class SwaggerConfig implements WebMvcConfigurer {
@Bean
public Docket customDocket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("swagger.demo.controller"))
.paths(PathSelectors.any())//过滤的路径
.build();
}
private ApiInfo apiInfo() {
Contact contact = new Contact("yebukong", "https://yebukong.com/", "yebukong@qq.com");
return new ApiInfoBuilder()
.title("swagger-demo API接口")
.description("简单的swagger UI用法展示")
.contact(contact)
.version("0.0.1")
.build();
}
/**
* 添加Swagger2静态文件映射
**/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
```
### API上加入Swagger相关注解
除了上述的SwaggerConfig类配置外，还需要在Controller上加入Swagger相关注解，以提供更详细的API信息，关于注解更详细的用法，可以参考[swagger常用注解说明](https://www.jianshu.com/p/12f4394462d5 "swagger常用注解说明")
```java
/**
* UserController
*
* @author Mine
* @date 2019/04/10 00:04:21
*/
//@Api用在类上，说明该类的作用
//参数详细说明 https://www.jianshu.com/p/12f4394462d5
@Api(tags = { "用户api组" }, protocols = "http", hidden = false)
@Controller()
@RequestMapping("/u")
public class UserController {
@ApiOperation(tags = { "公共api组" }, notes = "获取指定用户,通过URL传值", value = "获取指定用户")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true, paramType = "path") })
@ApiResponses({
@ApiResponse(code = 400, message = "请求参数没填好"),
@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对") })
@RequestMapping(value = "/{id}", method = RequestMethod.GET)
@ResponseBody
public R<UserInfo> get(@PathVariable("id") String id) throws Exception {
UserInfo ui = new UserInfo();
ui.setId(id);
ui.setName("Test");
ui.setPassword("code");
ui.setStatus("Vaild");
return R.ok(ui);
}
@ApiOperation(notes = "更新指定用户", value = "更新指定用户")
@ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户ID", required = true, paramType = "path") })
@RequestMapping(value = "/{id}", method = RequestMethod.POST)
@ResponseBody
public R<Object> update(@RequestBody() UserInfo userinfo) throws Exception {
System.out.println(userinfo);
return R.ok(null);
}
}
```
### 验证
在项目启动后访问以下路径验证：
API信息：http://localhost:8080/v2/api-docs
API信息展示页：http://localhost:8080/swagger-ui.html
效果图:
### 相关代码地址
Gitee: https://gitee.com/yebukong/swagger-demo
GitHub: https://github.com/yebukong/swagger-demo
### 参考链接
> https://www.cnblogs.com/getupmorning/p/7267076.html
> https://www.jianshu.com/p/12f4394462d5
:stuck_out_tongue:
------------
> 本文由 [叶不空](https://yebukong.com "叶不空") 创作，采用 [知识共享署名 4.0 国际许可协议](https://creativecommons.org/licenses/by/4.0/ "知识共享署名 4.0 国际许可协议")进行许可,转载请附上链接！
> 本文链接: [https://yebukong.com/article/1107706214319489025.html](https://yebukong.com/article/1107706214319489025.html "Swagger UI 简单使用")