JAVA

发布日期: 2018-09-25

更新日期: 2018-09-25

文章字数: 1.4k

阅读时长: 5 分

简介

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文档主页面