接口文档管理系列 OpenAPI规范及Swagger工具集

最新推荐文章于 2024-05-14 09:40:10 发布
最新推荐文章于 2024-05-14 09:40:10 发布
阅读量3.9k 收藏 11
点赞数 4
文章标签： API 接口 文档 接口文档 swagger
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/wangxudongx/article/details/107448041
版权

接口设计及文档管理系列 各个工具及概念介绍

在这里插入图片描述

OpenAPI

在互联网时代，把网站的服务封装成一系列计算机易识别的数据接口开放出去，供第三方开发者使用，这种行为就叫做开放网站的API，与之对应的，所开放的API就被称作OpenAPI。

在这里插入图片描述

在这里插入图片描述

OpenAPI规范

什么是OpenAPI规范？

OpenAPI规范（以前称为Swagger规范）是定义RESTful接口的世界标准。OAS使开发人员能够设计与技术无关的API接口，从而构成其API开发和使用的基础。

OpenAPI规范的简称为：OAS

OpenAPI规范的历史

VersionDateNotes
3.0.12017-12-06Patch release of the OpenAPI Specification 3.0.1
3.0.02017-07-26Release of the OpenAPI Specification 3.0.0
3.0.0-rc22017-06-16rc2 of the 3.0 specification
3.0.0-rc12017-04-27rc1 of the 3.0 specification
3.0.0-rc02017-02-28Implementer’s Draft of the 3.0 specification
2.02015-12-31Donation of Swagger 2.0 to the Open API Initiative
2.02014-09-08Release of Swagger 2.0
1.22014-03-14Initial release of the formal document.
1.12012-08-22Release of Swagger 1.1
1.02011-08-10First release of the Swagger Specification

OpenAPI是规范的正式名称。该规范的开发是由OpenAPI Initiative推动的，该倡议涉及更多来自技术领域不同领域的30个组织-包括Microsoft，Google，IBM和CapitalOne。领导Swagger工具开发的公司Smartbear Software也是OpenAPI Initiative的成员，帮助领导了规范的发展。

OpenAPI规范Github上的标准文档

OpenAPI描述文档格式

OpenAPI描述文档可以是JSON或者YAML格式的其中一种。

建议将根OpenAPI文档命名为openapi.json或openapi.yaml。

格式
符合OpenAPI规范的OpenAPI文档本身就是JSON对象，可以用JSON或YAML格式表示。

例如，如果一个字段具有数组值，则将使用JSON数组表示形式：

{
“字段”：[ 1，2，3 ]
}
规范中的所有字段名称均区分大小写。

该模式公开两种类型的字段：固定字段（具有声明的名称）和模式字段（Patterned），它们为字段名称声明正则表达式模式。

模式字段必须在包含的对象内具有唯一的名称。

为了保留在YAML和JSON格式之间往返的能力，建议使用YAML 1.2版以及一些其他约束：

定义
OpenAPI文件
定义或描述API的一个文档（或一组文档）。OpenAPI定义使用并符合OpenAPI规范。

详细的说明请看OpenAPI定义手册

Swagger specification

OpenAPI 2.0描述文档

在这里插入图片描述

OpenAPI 3.0描述文档

在这里插入图片描述

Swagger

OAS和Swagger
您不能不谈Swagger就谈OAS。SmartBear的Swagger项目是OAS的原始基础，它由Swagger规范和Swagger工具组成。Swagger社区负责构建工具的使用，以在整个API生命周期中充分利用OAS的功能。

Swagger是什么？它能干什么？

Swagger提供了最简单易用的工具，以充分利用OpenAPI规范（OAS）的所有功能。

Swagger是与用于实现OpenAPI规范的一些最著名，使用最广泛的工具相关联的名称。Swagger工具集包括开源工具，免费工具和商业工具的组合，可在API生命周期的不同阶段使用。

包括并不限于

  • API设计
  • API开发
  • API文档
  • API测试

Swagger工具集介绍

Swagger UI

提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

在这里插入图片描述

使用频度：高

Swagger Editor

: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

然后，文档生成工具可以使用OpenAPI定义来显示API，代码生成工具可以使用各种编程语言来生成服务器和客户端，测试工具以及许多其他用例也可以使用OpenAPI定义。

Swagger 官方提供的在线 Editor

你也可以选择自己用Docker部署一个Swagger Editor

在这里插入图片描述
使用频度：一般

Swagger Codegen

Swagger Codegen是一个开源代码生成器，可直接从Swagger定义的RESTful API构建服务器存根和客户端SDK。

Swagger Codegen的源代码可以在GitHub中找到。

使用频度：低

通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在Swagger Editor中在线生成。

Swagger Codegen Documentation

Swagger Codegen 首页

Swagger Hub

适用于使用OpenAPI规范的团队和个人的设计和文档平台。

在您的组织中开发的API越多，就越需要建立通用的设计准则。SwaggerHub配备了内置的API标准化，使您的API符合您的组织设计准则。企业架构师可以确保团队成功遵循设计模式。

SwaggerHub用于标准化设计

Swagger Hub 首页

使用需要登陆哦（用github账号也可以）

在这里插入图片描述

使用频度：中等

Swagger Inspector

Swagger Inspector用于测试API

在开发过程中验证功能
不断要求开发人员仔细检查其API和端点是否在开发过程中按预期工作。Swagger Inspector提供了轻松检查API请求响应并确保它们按预期工作的功能。

使用频度：低

Springfox Swagger 根据代码（注解）生成接口文档

对于许多开发来说，编写这个OpenAPI的yml或json格式的描述文件，本身也是有一定负担的工作，特别是在后面持续迭代开发的时候，往往会忽略更新这个描述文件，直接更改代码。久而久之，这个描述文件也和实际项目渐行渐远，基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring，迅速将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式，在后面需求持续迭代的项目中，显得尤为重要和高效。

使用频度：高

Springdoc

Springdoc与OpenAPI 3兼容，并支持Spring WebFlux，而且可以和SpringFox共存。

下面两个图是在同一个项目中的swagger-ui中的截图

在这里插入图片描述

在这里插入图片描述

在这里插入图片描述

使用频度：高

Swagger 功能扩展插件 Knife4j 生成离线文档

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!

knife4j的前身是swagger-bootstrap-ui，为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j

在这里插入图片描述

在这里插入图片描述

生成的接口文档
在这里插入图片描述

使用频度：高

乍一看，接口文档的管理用Swagger的工具挺多的，你可能会想到学习成本的问题，但是并不是上面说的所有工具都要使用的，我已经在上面标注了使用频度，频度低的完全可以不使用。

我的推荐是
SSM项目使用 SpringFox + Swagger-UI + Knife4j + Swagger Editor
SpringBoot项目使用 Springdoc + Swagger-UI + Knife4J + Swagger Editor

上面的搭配基本可以满足大部分场景了。

后面我会对这些模块展开介绍并给出Demo。

Hypertext Transfer Protocol (HTTP) Status Code Registry

1xx：信息性-接收到请求，继续处理
2xx：成功-已成功接收，理解并接受了操作
3xx：重定向-必须采取进一步的操作才能完成请求
4xx：客户端错误-请求包含错误的语法或无法被满足
5xx：服务器错误-服务器无法满足看似有效的请求

HTTP Status Codes

导读

接口文档管理系列 Spring MVC框架整合Swagger

接口文档管理系列 Springboot集成springdoc

wangxudongx
关注
  • 4
    点赞
  • 踩
  • 11
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
使用Swagger UI展示各种OpenAPI文档
qq_41898196的博客
05-08 353
启动http-server时，会有一些信息显示哪些地址可以输入。进入swagger-ui的源码目录,安装依赖。swagger ui 依赖Node.js，的项目目录，然后运行以下命令来启动。-p 后面是指定的端口号。
微软宣布在Azure API管理中预览OpenAPI规范V3
cpongo011702
08-14 176
最近，微软宣布在Azure API管理中支持OpenAPI规范V3，他们的服务允许创建、发布、监控和维护API。OpenAPI规范的使用是通过 OpenAPI .NET SDK完成的，并支持从它们的实现中抽象出API定义。OpenAPI规范（以前称为Swagger）提供了以独立于语言的方式描述RESTful Web服务的方法。随着OpenAPI的广泛采用，已经形成了一个多样化的生态系统，我们可以使...
推荐开源项目：OpenAPI-GUI——直观的OpenAPI 3.0定义编辑器
最新发布
gitblog_00085的博客
05-14 317
推荐开源项目：OpenAPI-GUI——直观的OpenAPI 3.0定义编辑器 项目地址:https://gitcode.com/Mermade/openapi-gui 项目介绍 OpenAPI-GUI 是一个专为创建和编辑OpenAPI 3.0.x JSON或YAML定义设计的图形用户界面工具。无论是用于构建新的还是编辑现有的定义，这个工具都非常实用。此外，它还支持将导入的OpenAPI 2.0...
了解OpenApi和Swagger
2301_78276982的博客
01-03 1523
这些资料，对于【软件测试】的朋友来说应该是最全面最完整的备战仓库，这个仓库也陪伴上万个测试工程师们走过最艰难的路程，希望也能帮助到你！
Swagger(一) Swagger/Springfox 入门简介
奥迪的博客
09-12 7478
Swagger/Springfox 入门简介 一、 Swagger 简介 1 前言 接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要，但是由于项目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接口文档和实际情况不一致。 很多人员会抱怨别人写的接口文档不规范，不及时更新。当时当自己写的时候确实最烦去写接口文档。这种痛苦只有亲身经历才会牢记于心。 如果接口文档可以实时动态生成就不会出现上面问题。 Swagger 可以完美的解决上面..
swaggerUI不好用，试试这个openapiUI?
一步一个脚印
01-08 1327
基于swaggger2, openapi3规范的UI文档
【区分】swagger和openapi，到底区别在哪儿？
杨建荣的学习笔记
11-20 1011
统一的API接口平台有了统一的API接口平台，不管对内还是对外，都能更好做到：统一接口开发、统一接口管理、统一接口开放服务。统一接口开发：包括API接口的命名、分类、格式、接口文档、接口变更记录、接口发布、接口测试、接口日记等，都要统一风格、规范标准和约束。统一接口管理：包括API接口的升级、增加参数、部署、性能监控、错误日志，同时结合开发、测试、运维、文档等形成整套的研发体系和闭环。统一接口开放...
swagger_to_uml:将OpenAPI规范（aka Swagger）转换为PlantUML图
05-03
它将创建文件petstore_example/swagger.puml ，然后可以使用PlantUML将其转换为PNG图像，并具有以下内容： plantuml petstore_example/swagger.puml -tpng 请注意，您需要为此安装和 。 安装 该脚本与Python 3一起...
apispec：可插拔的API规范生成器。 当前支持OpenAPI规范（fka Swagger规范）。
02-04
apispec通过apispec.core模块提供了一个接口，可以将这些规范以JSON或YAML格式导出，便于与其他OpenAPI兼容的工具进行交互，例如Swagger UI或Postman。 apispec与Flask的集成使得在基于Flask的应用中定义和生成API...
ipfs-swagger：[WIP] IPFS Rest API Swagger规范文档（OpenAPI）
02-02
通过这个Swagger规范文档，开发者可以利用现有的Swagger工具链进行API的测试、代码生成、文档生成等，大大简化了与IPFS API交互的复杂度，提高了开发效率。对于想要接入IPFS服务的开发者来说，这是一个非常有价值的...
Swagger转JMeter脚本工具
05-24
Swagger.json文件就是遵循OAS规范的文档。 2. **RESTful API**：Representational State Transfer（REST）是一种网络应用程序的设计风格和开发方式，基于HTTP协议，以资源为中心，使用URI标识资源，通过HTTP方法...
open api文档自动生成工具
02-06
自己开发的，可以通过在线编辑JSON数据自动生成HTML API说明文档，分享一下！
openapi-preview:使用Swagger UI预览OpenAPI规范
05-07
OpenAPI预览 使用预览OpenAPI规范 aasaam软件开发小组
asp.net core api+jwt+swagger CRM管理系统 后台接口
11-29
此外，Swagger还支持OpenAPI规范，使得API的描述文件可以被自动化工具理解和生成代码，提高了开发效率。 在这个CRM系统的后台接口中，ASP.NET Core API负责处理来自前端的HTTP请求，执行业务逻辑，并通过JWT实现...
laravel-openapi：为Laravel应用程序生成OpenAPI规范
02-04
`laravel-openapi` 是一个针对Laravel框架的工具，用于自动生成符合OpenAPI规范的文档，帮助开发者更高效地管理他们的API接口。 ### OpenAPI规范介绍 OpenAPI规范是一种语言无关的、JSON格式的规范，用于描述HTTP...
openapi-specs:Apideck API的OpenAPI规范
04-12
OpenAPI规范，也被称为OpenAPI Specification (OAS)，是一个用于描述RESTful API...同时，OpenAPI规范的标准化使得自动化工具（如代码生成器、文档生成器、测试工具）能够更好地支持Apideck API，提升整体的开发体验。
springfox集成openapi实践
liaomin416100569的专栏
03-14 1102
一 。openapi介绍  OpenAPI的前身是swagger规范。Swagger是一套有助于前后端分离，接口管理和测试工具集  SwaggerTM是一个用于描述和文档化RESTful接口的项目。 Swagger规范定义了一系列的文件，用以描述API。这些文件可以被Swagger-UI项目用于展示API，也可以被Swagger-Codegen项目用于生成代码。一些其他的工具也可以利用这些文件，例...
Swagger UI 2.x、3.x 可视化 web API 文档
蚩尤后裔-汪茂雄
09-28 4220
目录 Swagger 概 述 Swagger 快速入门 Swagger 常用注解 Swagger 概 述 1、Swagger 官网：https://swagger.io/ 提供了以下几种开源工具，分别提供了相应的功能，本文只关心 Swagger UI 。 Swagger Codegen 通过 Codegen 可以将描述文件生成 html 格式和 cwiki 形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过 jar 包，docker，node 等方式在本地化执行生成。
Swagger 规范
彳亍
07-21 1304
简介 Swagger Specification（Swagger 规范），现在称作 OpenAPI Specification （OpenAPI 规范）。 OpenAPI 规范定义了如何去描述你的 API 信息。 OpenAPI 规范允许你以 json 或 yaml 的语法格式，来编写 Swagger 文件。 基本结构 在 Swagger 文件中，你可以使用 json 或 yaml 的语...
openapi接口规范 examples
05-23
OpenAPI（前称Swagger）是一个用于设计、构建、文档化和使用 RESTful API 的开放源代码工具集。它使用 JSON 或 YAML 格式来描述 API，包括 API 的请求和响应参数、操作、身份验证等信息。以下是一个简单的 OpenAPI 规范示例： ```yaml openapi: 3.0.0 info: title: My API version: 1.0.0 servers: - url: https://api.example.com/v1 paths: /users: get: summary: Get a list of users operationId: getUsers responses: '200': description: OK content: application/json: schema: type: array items: type: object properties: id: type: integer name: type: string post: summary: Create a new user operationId: createUser requestBody: required: true content: application/json: schema: type: object properties: name: type: string responses: '201': description: Created content: application/json: schema: type: object properties: id: type: integer name: type: string ``` 在这个示例中： - `openapi` 指定了所使用的 OpenAPI 版本。 - `info` 包含了 API 的基本信息，如标题和版本号。 - `servers` 定义了 API 的 URL。 - `paths` 定义了 API 的所有路径和操作。在这个示例中，我们定义了一个 `/users` 路径，包含了 `get` 和 `post` 操作。 - `get` 操作定义了获取用户列表的方式。它有一个 `summary` 描述、一个 `operationId` 标识符和一个 `responses` 对象，其中包含了 HTTP 响应码和相应的响应体。 - `post` 操作定义了创建新用户的方式。它有一个 `summary` 描述、一个 `operationId` 标识符、一个 `requestBody` 对象，其中包含了请求体的参数和类型，以及一个 `responses` 对象，其中包含了 HTTP 响应码和相应的响应体。 当你使用 OpenAPI 规范设计和构建 API 时，你可以使用这个示例作为参考，定义你的 API 的所有路径、操作和参数。

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

抵扣说明：

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

余额充值