简介

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 可以看到如下界面：

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：

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

然后就可以看到：

8.png

在项目中添加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：

9.png

在Spring Cloud项目中集成使用

在Spring Cloud中我们的服务都会注册在Eureka Server中，如下所示：

10.png

此时当我们点击红框中的服务时，返回的是空，无法查看具体的服务信息，接下来在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使用

11.png

YApi

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

12.png

RAP

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

13.png