简介
Swagger 是一个可以用来构建API服务文档的工具，并且API文档可以和代码服务实时更新，保持一致，提供了UI界面可以直接查看文档。同时还可以进行功能测试。
在Spring Boot项目中集成使用
1.新建项目并添加相关依赖
- Springfox-swagger2
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
- Springfox-swagger2-ui
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2-ui</artifactId>
<version>2.4.0</version>
</dependency>
2.添加配置类
@EnableSwagger2
@Configuration
public class SwaggerConfig {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 当前包路径
.apis(RequestHandlerSelectors.basePackage("cn.leon.leonswagger.controller"))
.paths(PathSelectors.any())
.build();
}
//构建api文档的详细信息函数
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("Leon测试Swagger")
//创建人
.contact(new Contact("Leon", "http://www.dujinghua.cn", ""))
//版本号
.version("1.0")
//描述
.description("API 描述")
.build();
}
}
3.为服务类添加注解
为提供接口服务的Controller类添加注解：@Api
@Api("swagger测试相关api")
public class LeonController {
}
4.为方法添加注解
在上面创建的LeonController类中添加方法,并在方法上添加相关注解：
/**
* Get请求测试
*/
@ApiOperation(value = "根据id查询商品详情", notes = "查询某个商品的详细信息")
@ApiImplicitParam(name = "id", value = "商品id", paramType = "path", required = true, dataType ="String")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户id", dataType = "String", paramType = "path", example = "1112")
})
@ApiResponses({
@ApiResponse(code = 500, message = "服务器内部错误"),
@ApiResponse(code = 404, message = "找不到请求路径")
})
@RequestMapping(value = "getGoods/{id}", method = RequestMethod.GET)
public String GetGoods(@PathVariable String id) {
return "Leon-商品ID : " + id;
}
5.访问文档
运行项目，访问地址：http://localhost:8080/swagger-ui.html 可以看到如下界面：
点击leon-controller可以看到方法的描述：
详细参数介绍
@EnableSwagger2 @Configuration
配置类需要添加的注解，声明为Swagger
@ApiOperation
指定接口方法的说明，如果方法不加此注解，说明默认为方法名称：
@ApiImplicitParams @ApiImplicitParam
接口详细描述的参数信息：
其中 ApiImplicitParam 为具体的参数，里面的配置 paramType 需要注意：
paramType代表参数放在哪个地方
- header-->请求参数的获取：@RequestHeader
- query-->请求参数的获取：@RequestParam
- path（用于restful接口）-->请求参数的获取：@PathVariable
- body（不常用）
- form（不常用）
@ApiResponses
接口返回信息描述：
测试
除了用作静态接口文档，swagger还可以进行测试，直接看到接口调用的返回结果，在参数中输入数值，然后点击 try it out 按钮，就可以查看详细调用结果：
注：如果发现请求返回结果有问题，可以先查看请求的完整地址，是否是正确的格式
如果接口方法中不加任何描述，那么会按照方法的参数默认生成描述，并且参数都是必须的（requeired）,测试的不输入参数会提示报错：
返回json数据
目前接口返回一般都是json数据，在Swagger中，可以指定返回为json格式数据，在ApiOperation注解中添加produces：
@ApiOperation(value = "根据id查询商品详情", notes = "查询某个商品的详细信息",produces = "application/json")
然后就可以看到：
在项目中添加JSON依赖：
<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.8.0</version>
</dependency>
然后返回数据时返回json格式数据：
@RequestMapping(value = "getGoods/{id}", method = RequestMethod.GET)
public String GetGoods(@PathVariable String id) {
String info = "Leon-商品ID : " + id;
JsonObject jsonObject = new JsonObject();
jsonObject.addProperty("info", info);
return jsonObject.toString();
}
重新在Swagger页面中测试，可以看到返回结果为json：
在Spring Cloud项目中集成使用
在Spring Cloud中我们的服务都会注册在Eureka Server中，如下所示：
此时当我们点击红框中的服务时，返回的是空，无法查看具体的服务信息，接下来在Spring Cloud集成Swagger。
首先为注册到Eureka Server上的服务添加配置：
eureka:
client:
service-url:
defaultZone: http://root:123456@localhost:7776/eureka/
instance:
status-page-url: http://localhost:${server.port}/swagger-ui.html
然后重启服务重新注册即可，然后在注册中心的界面，点击该服务就可以自动跳转到Swagger文档主页面
替代产品
除了使用Swagger提供项目API文档，还有其他一些不错的选择。Swagger的好处是可以根据代码变动随时更新内容并且可以测试，但是也有一些不太方便的地方：
- 和代码耦合在一起，是代码看起来比较臃肿
- 如果代码没有写完，那么接口文档就无法完成
- 项目服务启动才能访问接口文档，如果是公司内网开发，离开环境就无法查看。或者后端开发停掉服务，前端开发就看不到文档了
这里介绍几种其他的接口文档方案,具体选中哪种每个团队都会有不同的选择：
Easy Mock
https://easy-mock.com/login
是一个可视化，并且能快速生成模拟数据的服务。可以在线生成模拟接口，能够随机产生数据，也支持结合Swagger使用
YApi
https://yapi.ymfe.org/
可视化操作配置，同样非常方便
RAP
http://rapapi.org/org/index.do
阿里妈妈前端团队出品的开源接口管理工具RAP第二代
