在Spring Cloud中使用Swagger自动构建API接口文档

简介

Swagger 是一个可以用来构建API服务文档的工具,并且API文档可以和代码服务实时更新,保持一致,提供了UI界面可以直接查看文档。同时还可以进行功能测试。

在Spring Boot项目中集成使用

1.新建项目并添加相关依赖

  • Springfox-swagger2

    1
    2
    3
    4
    5
    <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
    </dependency>
  • Springfox-swagger2-ui

    1
    2
    3
    4
    5
    <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2-ui</artifactId>
    <version>2.4.0</version>
    </dependency>

2.添加配置类

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
@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

1
2
3
4
@Api("swagger测试相关api")
public class LeonController {
}

4.为方法添加注解

在上面创建的LeonController类中添加方法,并在方法上添加相关注解:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/**
* 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 可以看到如下界面:
1.png

点击leon-controller可以看到方法的描述:

2.png

详细参数介绍

@EnableSwagger2 @Configuration

配置类需要添加的注解,声明为Swagger

@ApiOperation

指定接口方法的说明,如果方法不加此注解,说明默认为方法名称:
3.png

@ApiImplicitParams @ApiImplicitParam

接口详细描述的参数信息:
4.png

其中 ApiImplicitParam 为具体的参数,里面的配置 paramType 需要注意:

paramType代表参数放在哪个地方

  • header–>请求参数的获取:@RequestHeader
  • query–>请求参数的获取:@RequestParam
  • path(用于restful接口)–>请求参数的获取:@PathVariable
  • body(不常用)
  • form(不常用)

@ApiResponses

接口返回信息描述:
5.png

测试

除了用作静态接口文档,swagger还可以进行测试,直接看到接口调用的返回结果,在参数中输入数值,然后点击 try it out 按钮,就可以查看详细调用结果:
6.png

注:如果发现请求返回结果有问题,可以先查看请求的完整地址,是否是正确的格式

如果接口方法中不加任何描述,那么会按照方法的参数默认生成描述,并且参数都是必须的(requeired),测试的不输入参数会提示报错:
7.png

返回json数据

目前接口返回一般都是json数据,在Swagger中,可以指定返回为json格式数据,在ApiOperation注解中添加produces:

1
@ApiOperation(value = "根据id查询商品详情", notes = "查询某个商品的详细信息",produces = "application/json")

然后就可以看到:
8.png

在项目中添加JSON依赖:

1
2
3
4
5
<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.8.0</version>
</dependency>

然后返回数据时返回json格式数据:

1
2
3
4
5
6
7
@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:
9.png

在Spring Cloud项目中集成使用

在Spring Cloud中我们的服务都会注册在Eureka Server中,如下所示:
10.png

此时当我们点击红框中的服务时,返回的是空,无法查看具体的服务信息,接下来在Spring Cloud集成Swagger。
首先为注册到Eureka Server上的服务添加配置:

1
2
3
4
5
6
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使用
11.png

YApi

https://yapi.ymfe.org/
可视化操作配置,同样非常方便
12.png

RAP

http://rapapi.org/org/index.do
阿里妈妈前端团队出品的开源接口管理工具RAP第二代

13.png

打赏一个煎饼果子!