在 Serverless 中使用 Swagger 进行 API 文档自动生成
随着云计算的不断发展，Serverless 架构已经成为越来越多的企业和开发者的首选。它能够极大地降低服务器维护和成本，并且能够实现弹性扩容。在使用 Serverless 架构时，文档自动生成也显得尤为重要，这大大降低了前后端开发沟通成本，提高了开发效率。而 Swagger 作为一个广泛应用的 API 文档工具，在 Serverless 中也发挥着不可替代的作用。本文将详细介绍如何在 Serverless 中使用 Swagger 进行 API 文档自动生成，方便您的开发工作。
一、Serverless 架构介绍
Serverless 架构，顾名思义，是指在开发应用时无需关注服务器架构，只需专注于业务逻辑的实现。这种架构方式的优点在于，无需关注服务器的硬件、软件环境，同时节省了维护和监控服务器的成本。
Serverless 通常被称为“无服务器”架构。当然，并不是说我们不需要服务器，而是说服务器不需要开发者自己去搭建和维护。
在 Serverless 中，开发者只需要专注于业务逻辑的实现，前端和后端可以分别使用不同的技术栈进行开发，通过 API 来进行通信。因此，在这种架构下，API 的管理和文档应运而生，成为了开发过程中不可或缺的部分。
二、Swagger 简介
Swagger 又称为 OpenAPI，是一种使用 JSON 或 YAML 进行编写的 API 规范。它支持多种编程语言，包括 Java、Python、Ruby、PHP 等。Swagger 可以实现 API 的完整管理，包括文档自动生成、请求信息格式校对、请求信息输入自动生成等。在 Serverless 中使用 Swagger 可以降低前后端开发沟通成本，提高开发效率，同时使管理和维护更加便捷。
三、利用 Serverless Framework 构建应用
Serverless Framework 是一个流行的 Serverless 应用框架，它支持各种云服务提供商，并且可以帮助我们更加方便地构建 Serverless 应用。下面我们将以使用 AWS Lambda 为例来介绍如何利用 Serverless Framework 配合 Swagger 进行文档自动生成。
- 首先需要安装 Serverless Framework，可以使用 npm 进行安装：
npm install -g serverless
- 创建一个新的 Serverless 应用，运行以下命令：
serverless create --template aws-nodejs --path my-api
这将创建一个名为 my-api 的名为 my-api 的应用程序，并在其中包含模板代码。默认情况下，Serverless Framework 会自动设置 AWS Lambda 执行角色，并处理其他安全设置。在项目文件夹中，创建一个新的文件夹来存放文档：
mkdir docs
- 安装 Swagger：
npm install swagger-jsdoc --save-dev npm install yamljs --save-dev
- 将以下代码添加到 serverless.yml 文件的 custom 部分：
// javascriptcn.com 代码示例
plugins:
- serverless-iam-roles-per-function
- serverless-plugin-warmup
custom:
documentation:
usagePlanName: "my-api"
apiInfo:
title: "My API"
version: "1.0.0"
description: "A simple API"
termsOfService: "https://example.com/terms/"
basePath: "/prod"
schemes:
- "https"
securityDefinitions:
MyAuthorization:
type: apiKey
name: Authorization
in: header
definition:
securitySchemes:
- MyAuthorization
openapi: '3.0.0'
options:
info:
version: '1.0.0'
title: 'My API'
description: 'A simple API'
yaml:
customTags:
- "!include"
- "!secure"
warmup:
# ... // 省略部分配置
iamRoleStatements:
# ... // 省略部分配置- 在项目根目录下创建一个 swagger.yaml 文件，并添加以下代码：
// javascriptcn.com 代码示例
swagger: '3.0'
openapi: 3.0.0
info:
title: My API
version: '1.0'
description: A simple API
termsOfService: 'https://example.com/terms'
servers:
- url: "/prod"
tags:
- name: users
description: API to manage users
components:
securitySchemes:
MyAuthorization:
type: apiKey
name: Authorization
in: header
security:
- MyAuthorization: []
paths:
/users:
get:
tags:
- users
summary: Get all users
operationId: getUsers
produces:
- application/json
responses:
200:
description: Successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
401:
description: Unauthorized
components:
schemas:
User:
type: object
properties:
id:
type: integer
name:
type: string
email:
type: string
phone:
type: string- 在项目根目录下创建一个 jsdoc.json 文件，包含以下内容：
// javascriptcn.com 代码示例
{
"swaggerDefinition": {
"openapi": "3.0.0",
"info": {
"title": "My API",
"version": "1.0.0",
"description": "A simple API",
"termsOfService": "https://example.com/terms/",
"contact": {
"name": "",
"email": ""
},
"license": {
"name": "",
"url": ""
}
},
"servers": [
{
"url": "/prod"
}
],
"securityDefinitions": {
"MyAuthorization": {
"type": "apiKey",
"name": "Authorization",
"in": "header"
}
},
"basePath": "/prod",
},
"apis": [
{
"spec": "swaggerConfig.js",
}
]
}- 在文档所在的文件夹中创建一个名为 swaggerConfig.js 的文件，包含以下内容：
// javascriptcn.com 代码示例 /** * @swagger * /users: * get: * tags: * - users * description: Get all users * produces: * - application/json * responses: * 200: * description: users * security: * - where: header * key: Authorization * type: apikey */ module.exports = '';
- 到这里配置完成了，运行以下命令上传到 AWS Lambda：
serverless deploy
- 验证文档，可以通过 https://serverlessapi.com/prod/documentation 进行访问，其中 serverlessapi.com/prod 是 API 的地址，documentation 是文档的名称。
四、总结
本文介绍了如何在 Serverless 中使用 Swagger 进行 API 文档自动生成，并详细介绍了整个流程。通过这种方式，我们可以实现快速、准确地生成 API 文档，为前后端开发提供了非常便捷的方式，也极大地提高了团队的工作效率。希望本文对您有所帮助，欢迎与我们分享您的观点和经验。
来源：JavaScript中文网 ，转载请注明来源 本文地址：https://www.javascriptcn.com/post/652d07647d4982a6ebe84e69