专栏首页杰的记事本Swagger自动生成API文档

Swagger自动生成API文档

最近安装并使用了一下Swagger-uiSwagger-editorSwagger-codegen,感觉还不错。

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger的目标是对REST API定义一个标准的和语言无关的接口,可让人和计算机无需访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过Swagger进行正确定义,用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似,Swagger消除了调用服务时可能会有的猜测。

Swagger是一组开源项目,其中主要要项目如下:

  • Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
  • Swagger-core: 用于、Servlets和Play框架进行集成。
  • Swagger-js: 用于JavaScript的Swagger实现。
  • Swagger-node-express: Swagger模块,用于node.js的Express web应用框架
  • Swagger-ui:一个无依赖的HTML、JS和CSS集合,可以为Swagger兼容API动态生成优雅文档。
  • Swagger-codegen:一个模板驱动引擎,通过分析用户Swagger资源声明以各种语言生成客户端代码。 C:\tools\swagger-codegen>mvn package C:\tools\swagger-codegen\modules\swagger-codegen-cli>mvn package C:\tools\swagger-codegen\modules\swagger-generator>mvn package C:\tools\swagger-codegen>java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l spring-mvc -o yqu/petstore/spring-mvc C:\tools\swagger-codegen\yqu\petstore\spring-mvc>mvn package 上述操作通过底层使用SpringFox库,会创建带有Swagger注释的Spring MVC框架代码,包括Controller和DTO类。这样将Swagger-ui部署到Web应用内,就可以通过http://server:8002/v2/sdoc.jsp在线访问API文档了。
  • Swagger-editor:可让使用者在浏览器里以YAML格式编辑Swagger API规范并实时预览文档。可以生成有效的Swagger JSON描述,并用于所有Swagger工具(代码生成、文档等等)中。

除了Swagger项目自身支持的Java、Scala和JavaScript语言,Swagger社区中还提供了很多支持其他语言的第三方工具,覆盖了Clojure、ColdFusion / CFML、Eiffel、Go、Groovy、.Net、Perl、PHP、Python、Ruby等各种编程语言。

Swagger总结

Swagger这类API文档工具可以满足下列需求:

  • 支持API自动生成同步的在线文档
    • 这些文档可用于项目内部API审核
    • 方便测试人员了解API
    • 这些文档可作为客户产品文档的一部分进行发布
  • 支持API规范生成代码,生成的客户端和服务器端骨架代码可以加速开发和测试速度

跟下列其他API文档工具相比,Swagger各有优缺点,但它功能最多、也是最流行的。

参考

Swagger官网
GitHub:Swagger
Swagger规范
SpringFox官网
GitHub:SpringFox
Spring Boot & Swagger UI

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • npm scripts的使用

    npm 允许在package.json文件里面,使用scripts字段定义脚本命令。

    javascript.shop
  • Nodejs跨平台环境变量设置cross-env

    在搭建公司新的前端工程的架构中,需要在在package.json的scripts标签下配置一系列命令,如下所示:

    javascript.shop
  • React Hooks vs React Component

    是不是简单多了!可以看到, Example变成了一个函数,但这个函数却有自己的状态(count),同时它还可以更新自己的状态(setCount)。这个函数之所以...

    javascript.shop
  • Spring Boot集成Swagger简易教程

      Swagger号称是史上最流行的、最好用的API接口文档构建工具,它支持多种语言包括Java在内,本文仅关注如何使用Spring Boot来集成Swagge...

    happyJared
  • Swagger详细了解一下(长文谨慎阅读)

    Swagger 是最流行的 API 开发工具,它遵循 OpenAPI Specification(OpenAPI 规范,也简称 OAS)。 Swagger 可以...

    IT苦逼一枚
  • 走进Java接口测试之接口管理工具Swagger2

    现在都奉行前后端分离开发和微服务大行其道,前后端技术在各自道路上越走越远。 前后端唯一联系变成了API接口,API文档变成了前后端开发人员&测试人员联系的纽带。...

    高楼Zee
  • 点击器木马“舟大师”暗刷流量 利用“肉鸡”操纵搜索结果

    【快讯】近日,有企业用户向火绒安全团队求助,称电脑CPU、带宽无缘无故占用变高,电脑出现发热、变慢等现象。火绒工程师远程查看后,在用户电脑中发现一组暗刷木马造成...

    用户6477171
  • 如何挂起Promise请求,refresh_token后再用新的access_token重新发起请求?

    接手老项目,需要写一个access_token刷新的逻辑,具体流程我就不赘述了,网上关于JWT刷新流程的文章有很多。我遇到的主要问题是,项目没有使用axios,...

    用户2141756
  • 案例 | 上海移动:数字化通向互联网的三个路标

    用互联网技术与理念改造企业架构 近年来,面对移动互联网大潮袭来及互联网企业业务的冲击,“转型互联网”成了传统企业的发展思路中反复提及的关键词。以基础电信运营商为...

    yuanyi928
  • 前端ReactJS技术介绍

    jeremyxu

扫码关注云+社区

领取腾讯云代金券