Swagger

简介

Swagger 是一套围绕 Open API 规范构建的开源工具，可以帮助设计，构建，记录和使用 REST API。Swagger 工具包括的组件：Swagger Editor ：基于浏览器编辑器，可以在里面编写 Open API规范。类似 Markdown 具有实时预览描述文件的功能。Swagger UI：将 Open API 规范呈现为交互式 API 文档。用可视化UI 展示描述文件。Swagger Codegen：将 OpenAPI 规范生成为服务器存根和客户端库。通过 Swagger Codegen 可以将描述文件生成 html 格式和 cwiki 形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。Swagger Inspector：和 Swagger UI 有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到 Swagger Hub 中。在 SwaggerHub 中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。使用 Swagger，就是把相关的信息存储在它定义的描述文件里面（yml 或 json 格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码

Springfox

使用 Swagger 时如果碰见版本更新或迭代时，只需要更改Swagger 的描述文件即可。但是在频繁的更新项目版本时很多开发人员认为即使修改描述文件（yml 或 json）也是一定的工作负担，久而久之就直接修改代码，而不去修改描述文件了，这样基于描述文件生成接口文档也失去了意义。Marty Pitt 编写了一个基于 Spring 的组件 swagger-springmvc。Spring-fox 就是根据这个组件发展而来的全新项目。Spring-fox 是根据代码生成接口文档，所以正常的进行更新项目版本，修改代码即可，而不需要跟随修改描述文件。Spring-fox 利用自身 AOP 特性，把 Swagger 集成进来，底层还是Swagger。但是使用起来确方便很多。
所以在实际开发中，都是直接使用 spring-fox。
附：官网地址
http://springfox.github.io/springfox/
附：官方源码
https://github.com/springfox/springfox

Swagger 极致用法

1 编写 SpringBoot 项目
编写 SpringBoot 项目，项目中 controller 中包含一个 Handler，测
试项目，保证程序可以正确运行。

@RestController
@RequestMapping("/people")
public class DemoController {
@RequestMapping("/getPeople")
public People getPeople(Long id, String name){
People peo = new People();
peo.setId(id);
peo.setName(name);
peo.setAddress("海淀");
return peo;
}
}

2 导入 Spring-fox 依赖
在项目的 pom.xml 中导入 Spring-fox 依赖。目前最新版本为 2.9.2，
所以导入的依赖也是这个版本。其中 springfox-swagger2 是核心内容
的封装。springfox-swagger-ui 是对 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>

3 添加注解
在 SpringBoot 的启动类中添加@EnableSwagger2 注解。
添加此注解后表示对当前项目中全部控制器进行扫描。应用
Swagger2

@SpringBootApplication
@EnableSwagger2
public class MyApp {
public static void main(String [] args){
SpringApplication.run(MyApp.class,args);
}
}

4 访问 swagger-ui
启动项目后在浏览器中输入http://ip:port/swagger-ui.html即可以
访问到 swagger-ui 页面，在页面中可以可视化的进行操作项目中所有
接口。