带有Swagger的Spring Rest API –公开文档
创建API文档后,将其提供给涉众非常重要。 在理想情况下,此发布的文档将具有足够的灵活性以解决任何最新更改,并且易于分发(就成本以及完成此操作所需的时间而言)。 为了使这成为可能,我们将利用我在上一篇文章中完成的详细介绍API文档创建过程的内容 。 结合使用Swagger UI模块和json中已发布的API文档,我们可以创建可用于与API交互的简单HTML文档。
与Swagger UI集成
Swagger UI的开发者将其描述为HTML,Javascript和CSS资产的无依赖集合,可从与Swagger兼容的API动态生成漂亮的文档和沙箱。 由于Swagger UI没有依赖关系,因此您可以将其托管在任何服务器环境或本地计算机上。 话虽如此,让我们看一下如何将Swagger文档提供给Swagger UI。 作为HTML,CSS和JS的静态集合,我们可以将其拖放到我们的项目中,而无需修改我们的pom.xml
或项目中的任何其他文件。 只需转到GitHub并下载最新文件即可。
完成后,只需提供指向您的API列表的链接。 只需打开index.html
并用您自己的默认API列表URL替换就可以了。 我的示例中的URL看起来像这样: http://[hostname]:[port]/SpringWithSwagger/rest/api-docs
。 保存此更改并部署应用程序和静态Swagger UI之后,您应该能够浏览API并与之交互。
API文档
根据我的示例,我可以访问以下URL http://localhost:8080/SpringWithSwagger/apidocs/
(由于我选择的部署方法的性质)。 如您所见,Swagger UI仅使用以json
格式发布的数据(先前已讨论)。 您会看到的第一件事是API列表,它使您可以浏览已发布的API的集合。
当您要浏览可用的操作时,只需单击一下所有简短说明的所有精美彩色列表,便可以知道下一步的导航位置。 颜色在整个清单中保持一致,并很好地补充了操作。
当您找到所需的操作时,便该该首先获取您要查找的信息了。 单击方法名称,将显示完整的方法说明以及参数和响应消息。 但是还有更多原因,因为您可以使用自己的API并测试您的方法。 提供所有必需的参数并点击“尝试一下!” 按钮,您可以检查您的应用程序服务器是否已启动并以预期的方式运行。 如果您的代码需要某种类型的文件上传(就像我的更新用户的头像逻辑一样),那么Swagger UI会提供方便的工具来使其尽可能地容易。
即使您能够进行一些快速的即席测试或检查,此工具也绝对不适合应用程序测试。 它所做的只是以一种易于阅读的方式提供API文档,如果您有需要的话,可以自己尝试该方法(以提高对文档的理解)。 我发现这很不错,因为您需要了解一下操作本身,并且它的可观察到的行为Swagger UI可以使您满意,如下所示。
擅长的地方
我真的很喜欢Swagger处理文档的方式以及Swagger UI呈现文档的方式。 以下几点使Swagger非常适合我的API文档需求:
- 语言不可知
- 在异构环境中工作或考虑将新语言和工具引入您的项目时,该资产具有极大的价值。
- 基于注释的文档
- 批注将文档绑定到代码,以单个生命周期创建一个单元。 这使得管理,发布和发布的整个过程变得更加容易,并允许进行自动化。
- 公开进行后期处理
- 拥有json形式的中间步骤可让开发人员将自定义脚本和转换器附加到流程中,以便根据涉众的需要生成各种格式的文档,例如PDF或Word文档。
- 丰富的模块和组件生态系统
- 如果浏览Swagger的可用模块和组件,您可能会惊讶于此工具花了多少时间。 那里有许多有用的组件,因此很有可能会找到您认为您的项目可能需要或受益的Swagger扩展。
- 外观精美的UI工具
- 因为我在UI方面不是很有才华,所以我很高兴不必烦恼如何创建,格式化,呈现和交付文档的方式。 我所需要的只是在源代码中提供相关信息,仅此而已。 框架负责其余的工作,而我很快就得到了及时的文档。 鉴于Swagger UI的性质,如果需要,可以很容易地向其添加自定义公司标识。
- 试试看! 选项
- 小事总是让我开心。 但是我认为,对整个团队来说,在文档中整齐地打包此选项(例如,在需要的地方,需要的时候)非常有益。
不足之处
我不会假装这是灵丹妙药,适合所有解决方案。 当然,在某些情况下,此类工具不是首选。 鉴于其年轻的年龄,仍有一些事情需要增加/改进。 但重要的是要声明该项目仍在开发中,并且日渐流行。 话虽这么说,我想指出一些我发现的问题,这些问题需要深入研究和其他工作。 在我的第一次尝试中,我将重点关注三个主要问题。
- 有条件地访问某些模型参数
- 根据您的需求(以及使用的Swagger版本),您可能会发现自己需要从Swagger UI和Swagger json隐藏某些模型参数。 但是,这比我预期的需要更多的工作,并且需要修改模型属性。 可以预期,随着Swagger及其相关组件的下一个主要版本的发布,情况会变得更好,但是在此之前,您不得不手动执行此操作。 如果您对如何实现此目标感兴趣,请查看我的下一篇名为Swagger的Spring Rest API –精调公开的文档。
- 文件上传及相关字段
- 您的某些API操作可能需要上传文件(例如我的头像更新方法)。 但是,要使操作细节看起来像我的示例中所呈现的那样,需要一点点的手工工作和规范筛选。 要摆脱与此问题相关的不需要的参数,请查看我的下一篇名为Swagger的Spring Rest API –精调公开的文档,我将在此详细介绍此问题以及如何在此处显示结果。
- API模型和XML
- Swagger声称它是json和XML的朋友。 在操作级别上肯定是正确的,但是,在模型表示方面,XML比json位居第二(由于与XML及其模式有关的技术复杂性)。 当前,Swagger UI中的所有API模型都显示为json实体(json和XML),这迫使我不要在
ProductsEndpoint
文档中声明响应类型(在我的SpringWithSwagger示例中,示例使用XML格式的端点)。 这是我尚未完全解决的问题,因此我有意选择在处理XML时不声明响应类型。
- Swagger声称它是json和XML的朋友。 在操作级别上肯定是正确的,但是,在模型表示方面,XML比json位居第二(由于与XML及其模式有关的技术复杂性)。 当前,Swagger UI中的所有API模型都显示为json实体(json和XML),这迫使我不要在
下一步是什么?
如果按照所有步骤进行操作,现在应该已经有适用于您的API的API文档/沙箱。 在我的下一篇名为Swagger的Spring Rest API的文章中,我将展示如何使用Swagger来微调已发布的文档-微调公开的文档。 该微型系列中使用的代码在GitHub上发布,并提供了所有讨论的功能和工具的示例。 请享受!
翻译自: https://www.javacodegeeks.com/2014/11/spring-rest-api-with-swagger-exposing-documentation.html
带有Swagger的Spring Rest API –公开文档相关推荐
- swagger api文档_带有Swagger的Spring Rest API –公开文档
swagger api文档 创建API文档后,将其提供给涉众很重要. 在理想情况下,此发布的文档将足够灵活以解决任何最后的更改,并且易于分发(就成本以及完成此操作所需的时间而言). 为了使之成为可能, ...
- swagger api文档_带有Swagger的Spring Rest API –创建文档
swagger api文档 使REST API易于使用的真正关键是好的文档. 但是,即使您的文档做得很好,您也需要设置公司流程的权利以正确,及时地发布它. 确保利益相关者按时收到是一回事,但是您也要负 ...
- 带有Swagger的Spring Rest API –创建文档
使REST API易于使用的真正关键是好的文档. 但是,即使您的文档做得不错,您也需要设置公司流程的权利,以正确,及时地发布它. 确保利益相关者按时收到是一回事,但是您也要负责API和文档中的更新. ...
- 带有Swagger的Spring Rest API –集成和配置
如今,公开的API终于获得了应有的关注,公司也开始意识到其战略价值. 但是,使用第三方API确实是一项繁琐的工作,尤其是当这些API维护不当,设计不当或缺少任何文档时. 这就是为什么我决定四处寻找可以 ...
- Spring Boot API 接口文档 Swagger 入门
转载自 芋道 Spring Boot API 接口文档 Swagger 入门 摘要: 原创出处 http://www.iocoder.cn/Spring-Boot/Swagger/ 「芋道源码」欢迎转 ...
- 芋道 Spring Boot API 接口文档 Swagger 入门
点击上方"芋道源码",选择"设为星标" 做积极的人,而不是积极废人! 源码精品专栏 原创 | Java 2020 超神之路,很肝~ 中文详细注释的开源项目 RP ...
- swagger php 生成api,blog/Swagger生成php restful API接口文档.md at master · lfq618/blog · GitHub...
Swagger生成php restful API接口文档 背景 我们的restful api项目采用yaf框架, 整体结构简单, 我们只需要用swagger扫描 application目录即可. 下面 ...
- Swagger 生成 PHP restful API 接口文档
需求和背景 需求: 为客户端同事写接口文档的各位后端同学,已经在各种场合回忆了使用自动化文档工具前手写文档的血泪史. 我的故事却又不同,因为首先来说,我在公司是 Android 组负责人,属于上述血泪 ...
- Swagger 生成 PHP API 接口文档
Swagger 生成 PHP API 接口文档 标签(空格分隔): php 1.概况 有同学反馈写几十个接口文档需要两天的工作量, 随着多部门之间的协作越来越频繁, 维护成本越来越高, 文档的可维护性 ...
最新文章
- 使用datatables实现列宽设置、水平滚动条、显示某列部分内容
- python自带gui_一个极简易上手的 Python GUI 库
- 多态基类与虚析构函数
- ubuntu创建、删除文件及文件夹,强制清空回收站方法
- 计算矩阵连乘积(动态规划)
- Bzoj 2453: 维护队列 Bzoj 2120: 数颜色 分块,bitset
- CentOS 6.5系统安装配置图解教程(详细图文)
- 数据分页 THINKPHP3.2 分页 三种分页方法
- 表白记 BFS求最短路径
- Linux使用技巧15则
- 有些卖花生的人6.5元拿货,却卖6元,这是怎么回事?求解?
- 简洁优雅的.net代码赏析
- BeX5安装遇到问题
- 天下数据服务器搭建网站,王者天下架设教程1-服务端配置.doc
- 华为matebook键盘失灵
- php 正则 标点符号,js正则匹配中文标点符号
- 客厅的走廊应该怎么去设计
- 安卓手机APP 开发
- linux磁盘变为raw,LINUX下如何挂载RAW格式的硬盘
- ALtera DE2开发板学习