RESTful API 作为现代 Web 应用的基础， 其规范性和可读性对于交互性相当的重要。Swagger 是一个流行的 API 文档生成工具，它可以帮助前端工程师们快速生成详细的 API 文档，并通过静态或动态交互的方式带来更佳的用户体验。那么，本篇文章将会讨论如何使用Swagger生成 RESTful API 文档。
什么是 Swagger？
Swagger (OpenAPI) 是一个 API 规范和工具集，它可以用以更好的描述 RESTful API 和生成相应的文档。Swagger 文档描述了 API 的端点、参数、请求和响应消息，以及授权和访问控制等功能。同时 Swagger 还提供了各种服务，包括从 OpenAPI 规范生成客户端和服务器端的代码、验证 API 和测试 API 的工具等。Swagger 致力于通过简化和标准化 RESTful API 的设计和利用，提高 API 开发的可重用性和良好互操作性。
如何生成 Swagger 文档？
Swagger 文档的生成需要标记 API 的源代码中的端点、参数、请求消息和响应消息等信息。因此，我们可以通过注释代码、使用 Swagger 的各种注解修饰代码等方式来生成 Swagger 文档。
注释代码
在文档标记方面，Swagger 官方提供了一些用注释的方式来读取 API 的相关信息：
-- -------------------- ---- -------
----------------------------
----- ----------------
---------------------- --- -----
--- --------- ----
---
---- -- --- -----------
---
----------
----
--------
-----------------
------- ----------
---
------ ------ ---可以从代码注释中学到以下信息：
- uri：通过这个路由可以访问到这个 API，应以 @api.route() 装饰器方式依附在 API 类的顶部实现之。
- HTTP 方法：展现在注释的函数之前是这个 API 所支持的 HTTP 请求方法。
- 请求参数：由标头、查询参数，路径参数或请求体参数指定。
- 响应：响应内容有其状态码、内容类型、schema 等属性。Schema 可用于指定响应主题的结构。
使用注解
Swagger 还提供了一种称为注解的方式来标记 API 操作。在 Flask 上，通过 Flask-RESTPlus 拓展可以实现这样的操作：
@api.response(404, 'Entity not found')
@api.doc(model=MyModel, body=MySchema)
class MyApi(Resource):
@api.doc(params={'id': 'An ID'})
@require_auth
def get(self, id):
return get_detail(id)这段代码为以下这些 API 元素定义了说明：
- 响应 404：在响应对象中定义了 o例外对象和第一条响应消息。
- 响应模型：指定了
MyModel必需的属性和类型。 - 请求体模型：指定了
MySchema必需的属性和类型。 - http 方法及参数：为接口函数添加 doc 注解，用于描述此接口方法的说明。
静态文档生成
Swagger-UI 是 Swagger 的前端工具，它利用 Swagger 规范生成用户友好的交互式文档。Swagger-UI 的行为可以通过加载 Swagger-UI 的源代码进行定制，如果希望使用 Swagger-UI 来开发 RESTful 的 Web 应用，则需要加载 Swagger UI 项目并嵌入 Swagger UI 的特定标记，例如：
-- -------------------- ---- -------
---- ------ ---
----- ---------------- ----------------------- --------------- --
---- --- ---
---- ------- ---
------
---- --------------------------------
---- -------- ---
------------- - -------- -- -
----- -- - -----------------
---- ------------------------------------------------------------------------------------------------------
------- ------------------------
-------- -
----------------------------
--
------- ------------------
--
--------- - --
-
---- --- ---
---- --------- ---
-------这种方式生成的文档适用于展示具体接口的信息，可以直接给开发者或调用者使用。
动态文档生成
除了静态生成的文档之外，Swagger 也可以通过集成到应用程序中以动态方式生成文档：
-- -------------------- ---- -------
---- -------------- ------ ---
---- ----- ------ -----
---- -------------- ------ ---------------
---- ---- ------ ---
----- -----------------------
----------------
--- ------------
---
------- ------------- ------ -- ------ ---- - ------ ------ -- ------
---- --- ----- --------- -- ---------------- -------- -------------
-------- --- ---------- ------ ----- --- --------------- ---------
---
------ ---------------
----- ------------------------- -----
----
--- - ---------------
----------------------------------- - -----
--- - ----------
---- -------------- --------- -----
-------------- ------ ------------- -----
----------------------
-
这种情况下，也可以利用 YAML 或 JSON 文件的形式，实现自定义且动态的 swagger 文档加载。同时，这种偏向于从应用代码中构建（以及放置）静态 UML 图。
总结
Swagger 大大提升了 RESTful API 的可读性和可维护性，实现 RESTful API 的时候考虑到这个工具，是一个不错的技术选择。当然，Swagger 真正能发挥作用的先决条件是要学会使用和使用好，这需要耐心的学习和实践。本文总结了静态和动态文档的使用、注释和注解方式的实现手段等，相信本文能够帮助你学习使用 Swagger 生成 RESTful API 文档，提升自己的开发能力。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6476d81e968c7c53b03766df