Swagger2配合YAPI自动生成文档

最新推荐文章于 2024-08-01 16:16:02 发布
最新推荐文章于 2024-08-01 16:16:02 发布
阅读量1.9w 收藏 22
点赞数 4
分类专栏： JAVA EE
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/herestay/article/details/89338483
版权

前置说明

编写API文档，可能是最为枯燥无味的工作了，大部分程序猿都不太愿意干这个活，但是大部分人还是苦于没有找到更好的解决方案来处理这个问题，或者之前的代码不允许去做类似的工作，只能老老实实自己去写API。

但是，作为新项目启动，必须提前考虑这个问题，解放程序员双手，让他们撸更多业务代码，而不是整天纠结文档方面的工作。

如果要做到这些，那必须有一个前置条件，那就是你的代码足够规范，实体类命名、注释完备、数据库描述完善。

数据库结构

数据表结构必须规范、字段描述、表描述、主键策略、非空定义

CREATE TABLE `t_website` (
  `id` varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL COMMENT '网站ID',
  `name` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '网站名称',
  `logo` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin DEFAULT '' COMMENT '网站LOGO',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='网站信息';

出入参实体

如下，是一个比较规范的入参样本，使用ApiModelProperty描述好了字段的基本信息、是否非空


/**
* <p>
* 语言设置请求类
* </p>
*
* @author 聪明笨狗
* @since 2019-04-13 10:47
*/
@Data
@EqualsAndHashCode(callSuper = false)
@Accessors(chain = true)
@ApiModel(value="网站信息", description="网站信息")
public class WebsiteReqDTO implements Serializable {

    private static final long serialVersionUID = 1L;
    
    
    @ApiModelProperty(value = "网站ID", required=true)
    private String id;
    
    @ApiModelProperty(value = "网站名称", required=true)
    private String name;
    
    @ApiModelProperty(value = "网站LOGO")
    private String logo;
    
}

控制器类

如下，是一个比较规范的Controller控制器类


/**
* <p>
* 语言设置控制器
* </p>
*
* @author 聪明笨狗
* @since 2019-04-13 10:47
*/
@Api(tags={"网站信息"})
@Controller
@RequestMapping("/admin/website")
public class WebsiteController extends BaseController {

    @Autowired
    private WebsiteService baseService;

    /**
    * 添加
    * @param reqDTO
    * @return
    */
    @ResponseBody
    @ApiOperation(value = "添加")
    @RequestMapping(value = "/add", method = { RequestMethod.POST})
    public ApiRest<WebsiteRespDTO> add(@RequestBody WebsiteReqDTO reqDTO) {
        //保存数据并返回数据
    }

    /**
    * 根据ID修改
    * @param reqDTO
    * @return
    */
    @ResponseBody
    @ApiOperation(value = "根据ID修改")
    @RequestMapping(value = "/update", method = { RequestMethod.POST})
    public ApiRest edit(@RequestBody WebsiteReqDTO reqDTO) {
        //保存数据并返回数据
    }

    /**
    * 批量删除
    * @param reqDTO
    * @return
    */
    @ResponseBody
    @ApiOperation(value = "批量删除")
    @RequestMapping(value = "/delete", method = { RequestMethod.POST})
    public ApiRest edit(@RequestBody DeleteReqDTO reqDTO) {
        //删除数据并返回结果
    }

    /**
    * 查找详情
    * @param reqDTO
    * @return
    */
    @ResponseBody
    @ApiOperation(value = "查找详情")
    @RequestMapping(value = "/detail", method = { RequestMethod.POST})
    public ApiRest<WebsiteRespDTO> find(@RequestBody FindReqDTO reqDTO) {
       //返回详情数据
    }
    
}

Swagger配置

Swagger2.java

/**
 * Swagger2配置
 */
@Configuration
@EnableSwagger2
@ConfigurationProperties(prefix = "swagger")
public class Swagger2 {

    private static final String BASE_PACKAGE = "com.mycompany";
    @Value("${swagger.enable}")
    private boolean enableSwagger;

    @Bean
    public Docket helloDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                //用于分组功能，也可以不配置
                .groupName("admin")
                //注册整体api信息
                .apiInfo(apiInfo())
                //swagger功能是否启用，可以通过配置设置，也可以先写死
                .enable(enableSwagger)
                .select()
                //指定扫描的包
                .apis(RequestHandlerSelectors.basePackage(BASE_PACKAGE))
                //设置此组只匹配admin/**的请求
                .paths(PathSelectors.ant("/admin/**"))
                .build();
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("后台管理项目")
                .description("通用的CRUD")
                .contact(new Contact("Van", "", ""))
                .version("1.0.0")
                .build();
    }

pom.xml


<!-- 引入swagger2包 -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>

<!-- 引入自带UI，可选-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

以上配置好以后就OK了，项目启动以后，通过以下URL可以访问到API文档的JSON数据：

带分组的：
http://localhost:8080/v2/api-docs?group=admin
不带分组的：
http://localhost:8080/v2/api-docs

访问URL返回以下JSON:


{
	"swagger": "2.0",
	"info": {
		"description": "通用的CRUD",
		"version": "1.0.0",
		"title": "后台管理项目",
		"contact": {
			"name": "Van"
		}
	},
	"host": "127.0.0.1:8080",
	"basePath": "/",
	"tags": [{
		"name": "网站信息",
		"description": "WebsiteController"
	}],
	"paths": {
		"/admin/website/add": {
			"post": {
				"tags": ["网站信息"],
				"summary": "添加",
				"operationId": "addUsingPOST",
				"consumes": ["application/json"],
				"produces": ["*/*"],
				"parameters": [{
					"in": "body",
					"name": "reqDTO",
					"description": "reqDTO",
					"required": true,
					"schema": {
						"$ref": "#/definitions/网站信息"
					}
				}],
				"responses": {
					"200": {
						"description": "OK",
						"schema": {
							"$ref": "#/definitions/接口响应"
						}
					},
					"201": {
						"description": "Created"
					},
					"401": {
						"description": "Unauthorized"
					},
					"403": {
						"description": "Forbidden"
					},
					"404": {
						"description": "Not Found"
					}
				},
				"deprecated": false
			}
		},
		"/admin/website/delete": {
			"post": {
				"tags": ["网站信息"],
				"summary": "批量删除",
				"operationId": "editUsingPOST",
				"consumes": ["application/json"],
				"produces": ["*/*"],
				"parameters": [{
					"in": "body",
					"name": "reqDTO",
					"description": "reqDTO",
					"required": true,
					"schema": {
						"$ref": "#/definitions/删除参数"
					}
				}],
				"responses": {
					"200": {
						"description": "OK",
						"schema": {
							"$ref": "#/definitions/接口响应"
						}
					},
					"201": {
						"description": "Created"
					},
					"401": {
						"description": "Unauthorized"
					},
					"403": {
						"description": "Forbidden"
					},
					"404": {
						"description": "Not Found"
					}
				},
				"deprecated": false
			}
		},
		"/admin/website/detail": {
			"post": {
				"tags": ["网站信息"],
				"summary": "查找详情",
				"operationId": "findUsingPOST",
				"consumes": ["application/json"],
				"produces": ["*/*"],
				"parameters": [{
					"in": "body",
					"name": "reqDTO",
					"description": "reqDTO",
					"required": true,
					"schema": {
						"$ref": "#/definitions/查询参数"
					}
				}],
				"responses": {
					"200": {
						"description": "OK",
						"schema": {
							"$ref": "#/definitions/接口响应«网站信息»"
						}
					},
					"201": {
						"description": "Created"
					},
					"401": {
						"description": "Unauthorized"
					},
					"403": {
						"description": "Forbidden"
					},
					"404": {
						"description": "Not Found"
					}
				},
				"deprecated": false
			}
		},

		"/admin/website/update": {
			"post": {
				"tags": ["网站信息"],
				"summary": "根据ID修改",
				"operationId": "editUsingPOST_1",
				"consumes": ["application/json"],
				"produces": ["*/*"],
				"parameters": [{
					"in": "body",
					"name": "reqDTO",
					"description": "reqDTO",
					"required": true,
					"schema": {
						"$ref": "#/definitions/网站信息"
					}
				}],
				"responses": {
					"200": {
						"description": "OK",
						"schema": {
							"$ref": "#/definitions/接口响应"
						}
					},
					"201": {
						"description": "Created"
					},
					"401": {
						"description": "Unauthorized"
					},
					"403": {
						"description": "Forbidden"
					},
					"404": {
						"description": "Not Found"
					}
				},
				"deprecated": false
			}
		}
	},
	"definitions": {


		"删除参数": {
			"type": "object",
			"required": ["ids"],
			"properties": {
				"ids": {
					"type": "array",
					"description": "要删除的ID列表",
					"items": {
						"type": "string"
					}
				}
			},
			"title": "删除参数",
			"description": "删除参数"
		},
		"接口响应": {
			"type": "object",
			"required": ["code"],
			"properties": {
				"code": {
					"type": "integer",
					"format": "int32",
					"description": "响应代码,0为成功,1为失败"
				},
				"data": {
					"type": "object",
					"description": "响应内容"
				},
				"msg": {
					"type": "string",
					"description": "响应消息"
				},
				"success": {
					"type": "boolean"
				}
			},
			"title": "接口响应",
			"description": "接口响应"
		},

		"接口响应«List«网站信息»»": {
			"type": "object",
			"required": ["code"],
			"properties": {
				"code": {
					"type": "integer",
					"format": "int32",
					"description": "响应代码,0为成功,1为失败"
				},
				"data": {
					"type": "array",
					"description": "响应内容",
					"items": {
						"$ref": "#/definitions/网站信息"
					}
				},
				"msg": {
					"type": "string",
					"description": "响应消息"
				},
				"success": {
					"type": "boolean"
				}
			},
			"title": "接口响应«List«网站信息»»",
			"description": "接口响应"
		},
		"接口响应«网站信息»": {
			"type": "object",
			"required": ["code"],
			"properties": {
				"code": {
					"type": "integer",
					"format": "int32",
					"description": "响应代码,0为成功,1为失败"
				},
				"data": {
					"description": "响应内容",
					"$ref": "#/definitions/网站信息"
				},
				"msg": {
					"type": "string",
					"description": "响应消息"
				},
				"success": {
					"type": "boolean"
				}
			},
			"title": "接口响应«网站信息»",
			"description": "接口响应"
		},
		"查询参数": {
			"type": "object",
			"required": ["id"],
			"properties": {
				"id": {
					"type": "string",
					"description": "要查询的ID"
				}
			},
			"title": "查询参数",
			"description": "查询参数"
		},
		"网站信息": {
			"type": "object",
			"required": ["code", "id", "name", "state"],
			"properties": {
				"id": {
					"type": "string",
					"description": "网站ID"
				},
				"name": {
					"type": "string",
					"description": "网站名称"
				},
				"logo": {
					"type": "string",
					"description": "网站LOGO"
				}
			},
			"title": "网站信息",
			"description": "网站信息"
		}
	}
}

导入接口到YAPI

切换到YAPI的数据管理选项卡

image

有两种方式导入YAPI

1、将JSON保存到文件，上传。
2、如果你的项目有外网URL的话，直接开启URL导入。
image

导入好的接口

image

image

总结

只要你的代码足够规范，使用此方案进行文档导入，可以节省90%的文档工作量，生成的内容只需要少量修改就可以直接交于前端同事对接，是不是美滋滋？

另外提供一个自己写的SpringCloud代码生成器，只需要要贴入建表语句，即可一键生成符合规范的DTO/Entity/Controller/Service/Mapper/

https://jeegen.com/

注：以上部分内容经过加工，只做演示用，并非真实代码
herestay
关注
专栏目录
【D3S】REST接口文档自动生成 - 集成smart-doc并同步配置到Torna
罗小爬的技术宝书
08-09 465
本文结合笔者开源项目d3s介绍了如何通过maven插件集成smart-doc，并同步接口文档到Torna。
使用 YApi 管理 API 文档，测试， mock
阿星君
06-29 240
前言 随着互联网的发展，API变的至关重要。根据统计，目前市面上有上千万的开发者，互联网项目超过10亿，保守统计涉及的 API 数量大约有 100 亿。这么大基数的API，只要解决某些共有的痛点，将会是非常有意义的事情。我们总结了API管理方面的问题，发现与API相关的文档，调试，测试和数据Mock 在工作中效率是非常低下的。 业务痛点 接口的维护管理非常耗时，大概占用了30%开发时间。后端程序员要维护对于他们冗余的文档，前端程序员又因为后端开发提供的文档不准确，导致浪费了大量的时间.
Yapi结合swagger备注自动生成接口文档
weixin_42115358的博客
07-02 758
Yapi结合swagger备注自动生成接口文档
golang swag 生成多个文档
白马啸西施
01-15 356
golang 通过swag生成多个文档
Spring Boot：Swagger生成接口文档并调试接口
最新发布
安晴晚风的博客
08-01 777
使用Swagger只需要按照它的规范去定义接口及接口相关的信息，就可以做到生成接口文档，以及在线接口调试页面。
swagger2接口如何导入yapi
u012758488的博客
01-06 1757
一、通过http://ip:port/项目路径/swagger-ui.html进行查看swagger2De 接口 二、如图： 选择swagger导入，开启url导入，http://{ip}:{port}/项目路径/v2/api-docs 执行数据导入操作
设置swagger文档自动同步到YApi
write less , do more
03-23 5768
SpringBoot项目引入swagger文档后，每次都要手工维护接口到YApi很麻烦，有没有设置自动化同步的办法？操作如下： 进入YApi后添加项目 添加完项目后，点击设置，配置基本项目信息，由于我这边走的是网关，所以接口基本路径设置了一个 /api的统一前缀。 设置完基本信息后，可以在环境配置里面设置不同环境的请求地址和请求头信息等 在swagger自动同步中设置要同步的信息 开启自动同步-》设置同步方式-》项目的swagger json地址（配置为项目的请求接口地址+/v2/api-docs）-》设
软件测试学习笔记丨har生成用例
Ceshiren666的博客
03-11 536
Har格式是指HTTP归档格式（HTTP Archive Format）。用于记录HTTP会话信息的文件格式。多个浏览器都可以生成 Har 格式的数据。
【swagger+yapi】proto+grpc+swagger结合yapi命令生成接口文档
码农印象
11-15 2292
1、环境 操作系统：ubuntu 18.04 go版本：1.14.2 docker版本：19.03.1 docker-compose版本：1.24.0 2、gRPC环境安装 # 启用 module模式 GO111MODULE="on" # 配置 goproxy go env -w GOPROXY="https://goproxy.io,https://goproxy.cn,direct" # 安装 grpc $ go get -u google.golang.org/grpc 3、安装 Protoc
Yapi集成到Jenkins实现接口自动化—最全面的流程讲解
weixin_35947769的博客
05-15 1654
Yapi集成到Jenkins实现接口自动化，判断执行结果，并发送飞书消息附带报告地址—最全面的流程讲解
前后端分离开发、Yapi、Swagger、项目部署
乌云的博客
04-20 979
前后端分离开发，就是在项目开发过程中，对于前端代码的开发由专门的前端开发人员负责，后端代码则由后端开发人员负责，这样可以做到分工明确、各司其职，提高开发效率，前后端代码并行开发，可以加快项目开发进度。
【自动生成接口文档】Springboot集成Swagger2并通过Yapi做接口管理
热门推荐
不是很懂
08-30 2万+
Springboot集成Swagger2并通过Yapi做接口管理
yapi 导出 word
weixin_43124963的博客
04-11 1400
yapi 导出 word 的两种方法
Yapi接口一键生成Java代码
淡淡的说非
06-05 2271
Java代码生成器，将Yapi上定义的接口一键生成Java代码，包含controller、service、entity，有完整的类结构、方法、变量等，可直接使用。
yapi通过swagger直接生成接口在线文档
tansitao110的博客
12-30 1020
yapi是一款很好的接口在线文档，比swagger的功能强大太多，现在许多公司也在使用yapi作为接口文档管理工具，并且yapi也提供通过swagger中的文档直接转换到yapi上。 如图 只要在红框住处填入swagger地址即可马上生成接口文档到yapi，是不是很方便 重点 现在重点讲解这个地址怎么填 1、首先打开自己项目的swagger地址。我的是http://127.0.0.1:50000/greencow/swagger-ui.html 2、图片中标红的地址就是目标地址，特别说明，只有yapi和项目
Spring Boot集成Swagger导入YApi@无界编程
无界编程
04-02 3413
接口APi开发现状 现在开发接口都要在类似YApi上写文档，这样方便不同的团队之间协作，同步更新接口，提高效率。 但是如果接口很多，你一个个手工在YApi去录入无疑效率很低。 如果是使用Spring Boot集成Swagger可以直接导入YApi非常方便，不过还有一些需要注意的事项。 1.Spring Boot集成Swagger 添加swagger相关的maven依赖 <...
swagger接口文档同步yapi定义标准
qq_40224163的博客
01-12 979
ApiModel 用于swagger标记实体类属性类型默认值描述valueString类名类的备用名称String“”类的详细描述parentClass[]{}继承该类的子类型数组referenceString“”指定对应类型定义的引用，覆盖指定的任何其他元数据。
swagger管理api,一键导出
u011602668的博客
03-26 2539
swagger管理api和导出
Web菜鸟入门教程 - Swagger实现自动生成文档
zhonglunshun的专栏
08-14 1414
如果是一个人把啥都开发了，那用不到Swagger-UI，但一般情况是前后端分离的，所以就需要告诉前端开发人员都有哪些接口，传入什么参数，怎么调用，返回什么。有了Swagger-UI就能把这部分文档编写的业务给省去了。Swagger-UI是HTML, Javascript, CSS的一个集合，可以动态地根据注解生成在线API文档。
评论 5
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值