hooyantsing's Blog

青铜篇_P17_使用swagger构建API接口文档

字数统计: 867阅读时长: 4 min
2020/07/15

使用swagger构建API接口文档

20年全新-Spring Boot 2.x从青铜到王者之青铜篇-打造精品中的精品-程序员-编程-架构师-SpringBoot

swagger构建API文档的优点

  • 代码变,文档变。

  • 跨语言性,支持40多种语言。

  • Swagger UI 呈现出来的是一份可交互式的API文档。

  • 将文档规范导入相关的SoapUI,自动地创建自动化测试。

    关于Spring依赖Jar包的命名规范

  • 官方:spring-boot-starter-swagger

  • 开发者命名:swagger-xxxx-spring-boot-starter
    开发者命名,就是个人开发的工具包,xxxx是个人的标志,这样做是为了避免引起误解。

将swagger引入至项目

依赖

1
2
3
4
5
6
7
8
9
10
11
12
13
<!--swagger核心-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>

<!--swaggerUI 可以通过浏览器访问-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>

使用

创建一个配置类。

创建一个 config 包里面创建一个 SwaggerConfig 类。

对此类加上 @Configuration@EnableSwagger2 两个注解。

@Configuration

告诉Spring这是一个配置类。

@EnableSwagger2

表示在这个类里启用swagger相关的东西

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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
package xyz.hooy.demo.bronze.p17;

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
@EnableSwagger2
public class SwaggerConfig {

/** 对文档基本信息的设置
* title API文档标题
* description 简单介绍
* termsOfServiceUrl 遵从的协议
* version api版本号
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springboot利用swagger构建api文档")
.description("简单优雅的restful风格")
.termsOfServiceUrl("http://www.zimug.com")
.version("1.0")
.build();
}

@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 扫描 launch 包下面的 "/rest/" URL路径下的内容作为接口文档构建的目标。
.apis(RequestHandlerSelectors.basePackage("com.zimug.boot.launch"))
.paths(PathSelectors.regex("/rest/."))
.build();
}
}

至此,重启项目,文档生成。

查看文档访问:http://localhost:8888/swagger-ui.html

例:

cfc4f81330991cf9adaf5ba0a98b3ea1.png

将英文字段的名称翻译成中文

不推荐,比较繁琐。

将注释组加在Controller类的方法上。

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
29
30
31
package xyz.hooy.demo.controller;

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import xyz.hooy.demo.bronze.p12.Result;

import java.util.Date;

public class ArticleController {

// 作用:将英文字段的名称翻译成中文。
@ApiOperation(value = "添加文章",notes = "添加新的文章",tags = "Article",httpMethod = "POST")
@ApiImplicitParams({
@ApiImplicitParam(name = "title",value = "文章标题",required = true,dataType = "String"),
@ApiImplicitParam(name = "content",value = "文章内容",required = true,dataType = "String"),
@ApiImplicitParam(name = "author",value = "文章作者",required = true,dataType = "String")
})
@ApiResponses({
@ApiResponse(code = 200,message = "成功",response = Result.class),
})

@PostMapping("/articles")
public Result saveArticle( @RequestParam String author ,
@RequestParam String title ,
@RequestParam String content ,
@RequestParam Date createTime ){
// more code ...
return new Result();
}
}

对JavaBean的字段加入中文说明

将注释组加在JaveBean的类和域上。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
package xyz.hooy.demo.bronze.p12;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
//用于说明这个类是用来做什么用的
@ApiModel(value = "通用响应数据结构类")
public class Result {
@ApiModelProperty(value = "请求响应状态码",example = "200、400、500")
int code;
@ApiModelProperty(value = "请求结果描述信息")
String message;
@ApiModelProperty(value = "请求结果数据")
Object data;
}
CATALOG
  1. 1. 使用swagger构建API接口文档
    1. 1.1. swagger构建API文档的优点
    2. 1.2. 关于Spring依赖Jar包的命名规范
    3. 1.3. 将swagger引入至项目
      1. 1.3.1. 依赖
      2. 1.3.2. 使用
      3. 1.3.3. @Configuration
      4. 1.3.4. @EnableSwagger2
    4. 1.4. 将英文字段的名称翻译成中文
    5. 1.5. 对JavaBean的字段加入中文说明