RESTful API (Representational State Transfer Application Programming Interface) 是一种流行的Web API设计方法，可能是跟进最为迅速的标准之一。Swift和Java等主要编程语言已经支持了RESTful API设计，使得它变得非常流行。Swagger是一种可帮你构建、文档化、测试和调试Restful API的强大工具。

Swagger是针对RESTful API的，它提供了以下优点：

快速构建REST API
自动生成API文档
一致的用户体验
API可视化
它允许使用者在不同语言之间切换，而不更改设计结构。
支持API的审核和自我在测

本篇文章会带你进入Swagger，让你对这个工具有深刻的了解如何在你的API中应用这个工具。所有的示例代码都基于 Node.js 和 SQL Server。

REST API设计

在RESTful API中，资源可以用URL表示。例如，如果你运行一个装修公司，那么你可以用以下URL来表示资源：

-- -------------------- ---- -------
-- ------
--- ---------

-- --------
---- ---------

-- --------
--- -------------

-- ------
--- -------------

-- ------
------ -------------

可以看到，每个URL的HTTP命令都代表了某一种资源。这是RESTful API的基本概念。RESTful API的好处还包括请求和响应内容可以是JSON、XML等格式。此外，使用RESTful API时，客户端和服务端可以独立进化，只需要满足共同的接口即可。

Swagger的基本概念

Swagger是由 Reverb Technologies 开发的一种API文档工具，它可以生成指导用API的HTML文档或可以参考的JSON文档。Swagger包括以下不同的关键组件：

内置的Swagger UI，可以可视化所有的API
Swagger编辑器，可以用于在线编辑和文档化API设计

除此之外，Swagger还提供了泛型的Swagger API和一套完整的API框架的详细文档。API的架构文档将根据固定的格式提供API的详细信息，包括API的URL、请求参数等等。接下来，我们将学习如何使用Swagger文档生成器来创建与更新RESTful API的文档。

首先，你需要配置一个开发环境，安装需要的依赖。这里我们使用Node.js和SQL Server。

// SQL Server
brew install mssql

// Node.js
brew install node

REST API实现

首先，我们需要安装Express，它是一个较为著名的Node.js的Web框架。

// 安装Express框架
npm install express --save

以下是在Express框架下设计REST API的示例代码。

-- -------------------- ---- -------
----- ------- - -------------------
----- ---------- - -----------------------
----- --- - -----------------

----- --- - ----------
---------------------------

----- ------ - -
  ----- -----------
  --------- -----------
  ------- --------- 
  --------- ---------- 
--

-- ------
-------------------- ------------- ---- -
  --- ---------------------------------------------- -- -
    ------ ---------------------------- - ---- ----------
  -------------- -- -
    --- ---- - ----------------
    -------------------------------------------- -----
    ---------------------------
    ------------
  ------------ -- -
    ---------------------- -------- ----------- ---
    ------------
  ---
---

-- --------
------------------------ ------------- ---- -
  --- ---------------------------------------------- -- -
    ------ --------------
    ------------ -------- --------------
    -------------- - ---- -------- ----- -- - -----
  -------------- -- -
    -------------------------------------------- -----
    ---------------------------------------
    ------------
  ------------ -- -
    ---------------------- -------- ----------- ---
    ------------
  ---
---

-- --------
--------------------- ------------- ---- -
  --- ---------------------------------------------- -- -
    ------ --------------
    -------------- ------------- --------------
    ----------------- ------------- -----------------
    -------------- ---- -------- ------ -------- ------ ---------- 
    ------ ------- -----------
  -------------- -- -
    -------------------------------------------- -----
    ---------------------------------------
    ------------
  ------------ -- -
    ---------------------- -------- ----------- ---
    ------------
  ---
---

-- --------
------------------------ ------------- ---- -
  --- ---------------------------------------------- -- -
    ------ --------------
    ------------ -------- --------------
    -------------- ------------- --------------
    ----------------- ------------- -----------------
    -------------- -------- --- ---- - ------ ------- - -------- 
    ------ ---------- ----- -- - -----
  -------------- -- -
    -------------------------------------------- -----
    ---------------------------------------
    ------------
  ------------ -- -
    ---------------------- -------- ----------- ---
    ------------
  ---
---

-- --------
--------------------------- ------------- ---- -
  --- ---------------------------------------------- -- -
    ------ --------------
    ------------ -------- --------------
    -------------- ---- -------- ------ --------- ----- -- - -----
  -------------- -- -
    -------------------------------------------- -----
    ---------------------------------------
    ------------
  ------------ -- -
    ---------------------- -------- ----------- ---
    ------------
  ---
---

----- ------ - --------------------------- -- ----- ---------- -
  ---------------- --- ------- -- ------ -----------------------
---

你可以看到，我们为每个API命令实现了一个相应的HTTP请求方法。HTTP的请求与响应处理功能可以使用Express路由的相应方法实现。当我们启动Express应用时，它在运行端口上监听对这些API的请求。

现在，接下来我们将给每个请求添加Swagger文档。

Swagger文档的实现

在这个步骤中，我们会开始创建Swagger文档，以便我们可以在API中完成文档的定义。我们将使用Swagger的JSON格式描述API的形式。以下是此RESTful API的Swagger文档。

-- -------------------- ---- -------
-
---------- --------
------- -
  -------- -------- -----
  -------------- ---- ------- -----
  ---------- -----
--
---------- -
  -
    ------ -----------------------
  -
--
-------- -
  ------------ -
    ------ -
      ---------- ----- --- -- --- -----------
      ------------ -
        ------ -
          -------------- -----
          ---------- -
            ------------------- -
              --------- -
                ------- -------------------------------
              -
            -
          -
        --
        ------ -
          -------------- --------- ------ -------
          ---------- --
        -
      -
    --
    ------- -
      ---------- -------- - --- ---------
    -
  --
  ----------------- -
    ------ -
      ---------- ----- - -------- ------- -- ----
    --
    ------ -
      ---------- -------- - -------- ------- -- ----
    --
    --------- -
      ---------- -------- - -------- ------- -- ----
    -
  -
--
------------- -
  ---------- -
    ---------- -
      ------- ---------
      ------------- -
        ----- -
          ------- ---------
        --
        ------- -
          ------- --------
        --
        ---------- -
          ------- --------
        -
      -
    --
    ----------- -
      ------- --------
      -------- -
        ------- ------------------------------
      -
    -
  -
-
-

在通过Swagger生成文档之前，你需要安装Swagger提供的覆盖在常规API工具之上的中间件。

// 安装Swagger中间件
npm install swagger-ui-express --save

安装中间件后，你应该在Express应用中添加以下代码以便使用文档：

const swaggerUi = require(‘swagger-ui-express’);
const swaggerDocument = require(‘./swagger.json’)

app.use(‘/api-docs’, swaggerUi.serve, swaggerUi.setup(swaggerDocument));

我们还将创建一个API验证器，它将验证API的每个请求是否即将变为替代请求。以下是通过 Node.js 支持的 Swagger Node代码包实现的该过程。

-- -------------------- ---- -------
----- -------------- - ------------------------------
----- --- - ----------

----- ------ - -
  -------- ---------
--

----------------------------- ------------- --------------- -
  -- ----- - ----- ---- -

  -----------------------------
  ----- ------ - ---------------- ---------- -
    ---------------------- -- ---- -------
  ---
---

现在，我们已经可以打开网站查看API文档了。

接下来，在你的文档说明中画出API的设计图。在设计图中，你应该包含一些重要的关键信息。例如，运行API所需要的参数、API返回的数据，以及所有支持的HTTP命令。此外，还应该包含其他有用的信息，如API的版本、URL和其他相关上下文信息。

总结

在这篇文章中，我们讨论了RESTful API和文档生成器Swagger。我们了解了如何使用Node.js和Express框架创建一个RESTful API，并使用Swagger文档生成器生成API的文档。

在开发RESTful API时，文档化是不可缺少的。通过Swagger，我们可以快速和轻松地文档化API，并为其他开发人员和消费者了解和接口提供正确的使用方法。Swagger对于RESTful API的设计是一种很有用的工具，它可以大大提高我们的效率和准确性，同时降低我们在头脑中构建我们API文档时的错误率。

来源：JavaScript中文网，转载请注明来源 https://www.javascriptcn.com/post/65a8ff5badd4f0e0ff2481fb

RESTful API 中的 Swagger 文档生成器

REST API设计

Swagger的基本概念

REST API实现

Swagger文档的实现

总结

纠错反馈