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来表示资源：

// 获取所有项目
GET /projects

// 创建一个新的项目
POST /projects

// 获取一个特定项目
GET /projects/:id

// 更新特定项目
PUT /projects/:id

// 删除特定项目
DELETE /projects/:id

可以看到，每个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的示例代码。

const express = require(“express”);
const bodyParser = require(“body-parser”);
const sql = require(“mssql”);

const app = express();
app.use(bodyParser.json());

const config = {
  user: “username”,
  password: “password”,
  server: “server”, 
  database: “database” 
};

// 获取所有项目
app.get(“/projects”, function(req, res) {
  new sql.ConnectionPool(config).connect().then(pool => {
    return pool.request().query(“SELECT * from Projects”)
  }).then(result => {
    let rows = result.recordset
    res.setHeader(“Access-Control-Allow-Origin”, “*”);
    res.status(200).json(rows);
    sql.close();
  }).catch(err => {
    res.status(500).send({ message: err.message });
    sql.close();
  });
});

// 获取一个特定项目
app.get(“/projects/:id”, function(req, res) {
  new sql.ConnectionPool(config).connect().then(pool => {
    return pool.request()
    .input(“id”, sql.Int, req.params.id)
    .query(“SELECT * from Projects where Id = @id”)
  }).then(result => {
    res.setHeader(“Access-Control-Allow-Origin”, “*”);
    res.status(200).json(result.recordset);
    sql.close();
  }).catch(err => {
    res.status(500).send({ message: err.message });
    sql.close();
  });
});

// 创建一个新的项目
app.post(“/projects”, function(req, res) {
  new sql.ConnectionPool(config).connect().then(pool => {
    return pool.request()
    .input(“Name”, sql.NVarChar, req.body.Name)
    .input(“Manager”, sql.NVarChar, req.body.Manager)
    .query(“INSERT INTO Projects (Name, Manager) OUTPUT inserted.* 
    VALUES (@Name, @Manager)”)
  }).then(result => {
    res.setHeader(“Access-Control-Allow-Origin”, “*”);
    res.status(201).json(result.recordset);
    sql.close();
  }).catch(err => {
    res.status(500).send({ message: err.message });
    sql.close();
  });
});

// 更新一个特定项目
app.put(“/projects/:id”, function(req, res) {
  new sql.ConnectionPool(config).connect().then(pool => {
    return pool.request()
    .input(“id”, sql.Int, req.params.id)
    .input(“Name”, sql.NVarChar, req.body.Name)
    .input(“Manager”, sql.NVarChar, req.body.Manager)
    .query(“UPDATE Projects SET Name = @Name, Manager = @Manager 
    OUTPUT inserted.* WHERE Id = @id”)
  }).then(result => {
    res.setHeader(“Access-Control-Allow-Origin”, “*”);
    res.status(200).json(result.recordset);
    sql.close();
  }).catch(err => {
    res.status(500).send({ message: err.message });
    sql.close();
  });
});

// 删除一个特定项目
app.delete(“/projects/:id”, function(req, res) {
  new sql.ConnectionPool(config).connect().then(pool => {
    return pool.request()
    .input(“id”, sql.Int, req.params.id)
    .query(“DELETE FROM Projects OUTPUT deleted.* WHERE Id = @id”)
  }).then(result => {
    res.setHeader(“Access-Control-Allow-Origin”, “*”);
    res.status(204).json(result.recordset);
    sql.close();
  }).catch(err => {
    res.status(500).send({ message: err.message });
    sql.close();
  });
});

const server = app.listen(process.env.PORT || 8080, function() {
  console.log(“App now running on port”, server.address().port);
});

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

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

Swagger文档的实现

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

{
“openapi”: “3.0.0”,
“info”: {
  “title”: “Project API”,
  “description”: “The Project API”,
  “version”: “1.0”
},
“servers”: [
  {
    “url”: “http://localhost:3000”
  }
],
“paths”: {
  “/projects”: {
    “get”: {
      “summary”: “Gets all of the projects.”,
      “responses”: {
        “200”: {
          “description”: “OK”,
          “content”: {
            “application/json”: {
              “schema”: {
                “$ref”: “#/components/schemas/Projects”
              }
            }
          }
        },
        “500”: {
          “description”: “Internal Server Error”,
          “content”: {}
        }
      }
    },
    “post”: {
      “summary”: “Creates a new project.”
    }
  },
  “/projects/{id}”: {
    “get”: {
      “summary”: “Gets a specific project by id.”
    },
    “put”: {
      “summary”: “Updates a specific project by id.”
    },
    “delete”: {
      “summary”: “Deletes a specific project by id.”
    }
  }
},
“components”: {
  “schemas”: {
    “Project”: {
      “type”: “object”,
      “properties”: {
        “id”: {
          “type”: “integer”
        },
        “name”: {
          “type”: “string”
        },
        “manager”: {
          “type”: “string”
        }
      }
    },
    “Projects”: {
      “type”: “array”,
      “items”: {
        “$ref”: “#/components/schemas/Project”
      }
    }
  }
}
}

在通过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代码包实现的该过程。

const SwaggerExpress = require(‘swagger-express-mw’);
const app = express();

const config = {
  appRoot: __dirname
};

SwaggerExpress.create(config, function(err, swaggerExpress) {
  if (err) { throw err; }

  swaggerExpress.register(app);
  const server = app.listen(3000, function() {
    console.log(‘Listening on port 3000’);
  });
});

现在，我们已经可以打开网站查看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文档的实现

总结

纠错反馈