使用swagger2构建API文档

使用swagger构建API文档有很多优点：

可以整合到代码中，在开发时通过注解，编写注释，自动生成API文档，保证文档时效性。

支持四十多种语言，具有良好的跨语言性。

可以将文档规范导入相关的工具，自动地创建自动化测试。

SwaggerUI得到的是一份可交互式的API文档，可以直接在文档页面尝试API的调用，省去了准备调用参数的过程。

生成文档

首先我们在.xml文件中引入swagger相关依赖：

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>2.6.1</version>
</dependency>

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>2.6.1</version>
</dependency>1234567891011复制代码类型：[java]

在com.javafamily.familydemo文件下创建config文件，并在config文件下创建

SwaggerConfig.java。

package com.javafamily.familydemo.config;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;// 表示当前类为配置类@Configuration// 启用SwaggerAPI文档@EnableSwagger2public class SwaggerConfig { private ApiInfo apiInfo() {  return new ApiInfoBuilder()
 .title("API")
 .description("一起看下API文档吧")
 .termsOfServiceUrl("http://www.JavaFamily.com")
 .version("V1")
 .build();
 } @Bean
 public Docket createApi() {  return new Docket(DocumentationType.SWAGGER_2)
 .apiInfo(apiInfo())
 .select() // 把根目录下的所有接口函数形成文档
 .apis(RequestHandlerSelectors.basePackage("com.javafamily.familydemo"))
 .paths(PathSelectors.regex("/.*"))
 .build();
 }
}12345678910111213141516171819202122232425262728293031323334353637复制代码类型：[java]

运行程序，在浏览器访问http://localhost:8888/swagger-ui.html

点击pets-controller

点击一个接口，里面的参数都能很详细的展示出来。

我们还可以通过tryitout来请求响应结果。

所以，API文档不仅有看的功能，还拥有调用的功能。

注解

对于全英文比较吃力的人员，swagger也支持中文的接口功能注释。

@ApiOperation(value = "添加宠物", notes = "添加一只宠物信息", tags = "Pets", httpMethod = "POST")@ApiImplicitParams({
   @ApiImplicitParam(name = "id", value = "宠物id", required = true, dataType = "long"),
   @ApiImplicitParam(name = "name", value = "宠物名称", required = true, dataType = "String"),
   @ApiImplicitParam(name = "varieties", value = "宠物品种", required = true, dataType = "String")
 })
 @ApiResponses({
   @ApiResponse(code = 200, message = "success!", response = Response.class),
 })
 @RequestMapping(value = "/pets", method = RequestMethod.POST)
 public Response savePets(@RequestBody Pets pets) {
  log.info("savePets" + pets);  return Response.success(petsService.savePets(pets));
 }1234567891011121314复制代码类型：[java]

这样我们就拥有了中文注释。

接下来我们看一下@ApiModel注解，它能够在API文档中解释字段用处。

@Data@ApiModel(value = "提供一个备用名")public class Response { @ApiModelProperty(value="判断请求是否成功")
 private boolean isok; @ApiModelProperty(value="状态码")
 private int code; @ApiModelProperty(value="信息描述")
 private String message; @ApiModelProperty(value="返回数据")
 private Object data;1234567891011复制代码类型：[java]
赞 (0)

相关推荐