
在项目开发中,接口文档一直是个头疼的问题。本来项目开发时间就紧张,还需要另外写文档给调用方看,但是不写又不行,无法沟通,写了还要随着项目迭代一直更新,费时费力。
那有没有工具能够识别我们的代码自动生成接口文档呢?答案是有的。这篇文章就介绍市面上常用的接口文档生成框架:Swagger-UI 的简单使用。
讲 Swagger-UI 前需先了解下 Swagger,https://swagger.io/,Swagger 是一个常用的接口工具。
官方给自己的定义是:THE WORLD’S MOST POPULAR API TOOLING。
Swagger-UI 只是其中的一块,主要是通过代码里的注解,生成在线的接口文档界面,以便沟通。
除了 Swagger-UI,Swagger 还有 Swagger Editor(在线编辑接口文档)和 Swagger Codegen(根据接口文档生成代码,可以生成各种语言的代码,厉害吧!)。
先看效果
首先来两张高清大图,看看生成的效果。
整合接入步骤
(以一个普通的 SpringMVC 项目为例)
加入必须的依赖包(maven)
1 | <dependency> |
代码方式添加相关配置
1 | package com.zhangzw.swagger.spring; |
修改 Controller 接口
1 | package com.zhangzw.swagger.web; |
如果接口使用 DTO 接收和返回数据,可以在 DTO 上加入注解,如:
1 | package com.zhangzw.swagger.web; |
结束
这样就可以了,是不是很简单?只需要加入一些注解,文档就生成了,对代码侵入很小,保证了文档与代码的同步,最重要的是效率高啊!^_^
相关链接
Swagger-UI 官网
官方 DEMO