Swagger UI 简单使用

## 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
效果图:
![API信息展示](https://img.yebukong.com/blog/1107706214319489025/swagger-show.png "API信息展示")
### 相关代码地址
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 简单使用")
                        
(°ο°)评论插件未能完成加载!