使用Swagger记录Express API

2020年12月30日11:11:41 发表评论 31 次浏览

本文概述

我们都知道记录API的重要性。就节点API而言, 无论它们是基于Express还是其他框架构建的, 你都可以找到许多开源选项。这些包括apiDoc, docbox, 和别的。

但是, 在本教程中, 我们将探索昂首阔步用法以及Express API。

Swagger是一组开源工具, 使你能够设计, 构建, 记录和使用RESTful Web服务。它被创建为主要不可知论的, 这意味着你可以将其与几乎任何你喜欢的语言和框架一起使用。

在我们的示例中, 我们将使用两个库:swagger-ui-express和swagger-jsdoc.

第一个是一个模块, 可让你提供Swagger UI(基于swagger-ui项目)swagger.json文件或内联对象。

第二个项目是关于使用Swagger集成JSDoc在整个代码中添加注释。这非常有用, 尤其是当你拥有大量的API和数十种模型时。

应用程序设置

在本教程中, 我们将不涉及与Express API构建相关的任何内容。我要提供这个现成的例子在执行之前必须克隆到本地计算机。

这是一个简单的API, 可让你管理内存中的图书清单。随你的定制随意增加它。

在你的应用程序中拥有此功能后, 请在终端中运行以下命令:

npm install
npm i swagger-ui-express swagger-jsdoc

这些将下载所需的依赖项并添加其他Swagger依赖项。

我们为制作了一个自定义演示.
不完全是。点击这里查看.

使用Swagger记录Express API1

接下来, 将以下导入添加到server.js文件:

var express = require("express"), bodyParser = require("body-parser"), swaggerJsdoc = require("swagger-jsdoc"), swaggerUi = require("swagger-ui-express");

这两个分别代表我们导入的库的对象。在应用程序的前面添加以下代码听功能:

const options = {
  definition: {
    openapi: "3.0.0", info: {
      title: "notlogy Express API with Swagger", version: "0.1.0", description:
        "This is a simple CRUD API application made with Express and documented with Swagger", license: {
        name: "MIT", url: "https://spdx.org/licenses/MIT.html", }, contact: {
        name: "notlogy", url: "https://notlogy.com", email: "info@email.com", }, }, servers: [
      {
        url: "http://localhost:3000/books", }, ], }, apis: ["./routes/books.js"], };

const specs = swaggerJsdoc(options);
app.use(
  "/api-docs", swaggerUi.serve, swaggerUi.setup(specs)
);

如你在第一行中看到的, 此配置对象设置了一个OpenAPI的版本到3.0.0。 Swagger利用了开放API规范, 该规范是RESTful API的一种与语言无关的标准接口, 使人类和机器无需访问源代码或检查网络流量即可了解Web服务的功能。

你可以参考官方文档了解每个版本的所有可用设置。在这里, 我们仅使用基础知识:API信息, 名称, 标题, 描述, 许可证, API所有者的联系方式等。

API的属性至关重要, 因为它会搜索模型和端点定义, 因此请确保正确告知它。

最后, 我们正在使用昂首阔步函数可扫描作为参数传入的选项, 并返回转换后的Swagger规范对象。反过来, 这一个可以与招摇设置过程。

现在, 你可以通过npm开始命令。访问以下页面时, 你会看到以下屏幕:http:// localhost:3000 / api-docs /网址:

Swagger用户界面。

第一印象:Swagger UI

请注意, 我们仍然没有在规范中定义任何操作。发生这种情况是因为我们需要将这些操作明确地映射到路由。否则, Swagger无法自行确定API端点。

(可选)你可以在你的UI中添加搜索栏, 以防API操作过多。为此, 将实现更改为以下内容:

app.use(
  "/api-docs", swaggerUi.serve, swaggerUi.setup(specs, { explorer: true })
);

现在, 搜索栏将显示:

启用了搜索栏的Swagger UI。

启用搜索栏的Swagger UI。

建立模型

像许多重要的框架和API架构一样, 数据被封装到模型中以变得更易于访问。 Swagger还希望你的API具有模型, 并由你定义它们。

去路线/books.js并将以下代码放在文件的开头:

/
  @swagger
   components:
     schemas:
       Book:
         type: object
         required:
           - title
           - author
           - finished
         properties:
           id:
             type: integer
             description: The auto-generated id of the book.
           title:
             type: string
             description: The title of your book.
           author:
             type: string
             description: Who wrote the book?
           finished:
             type: boolean
             description: Have you finished reading it?
           createdAt:
             type: string
             format: date
             description: The date of the record creation.
         example:
            title: The Pragmatic Programmer
            author: Andy Hunt / Dave Thomas
            finished: true
 /

还记得我们讨论过的JSDocs吗? JSDocs现在进入现场, 并通过以下方式帮助我们设置Swagger规范的其余部分:@昂首阔步注解。

在这里, 你可以根据需要定义任意多个模式。就我们而言, 我们只是在定义域图书.

required属性接收必须在请求中填写的属性列表。此步骤对于让人们知道使用你的API时必须发送的内容至关重要。

的属性属性描述有关模型属性的详细信息。每个属性必须具有一个名称, 其后是其类型, 描述(可选)和格式(你也可以验证值)。有关可用数据类型的完整列表, 请参阅Swagger数据类型.

最后, 你可以提供此模式模型的请求数据的示例。稍后将很有用。

重新启动应用并刷新页面后, 你会看到以下屏幕:

新书架构的屏幕截图。

新书架构已添加。

好多了, 不是吗?

但是, 我们仍然没有任何操作。让我们解决这个问题。在上一个JSDoc注释之后, 添加以下内容:

/
  @swagger
  tags:
    name: Books
    description: API to manage your books.
 /

/
  @swagger
  path:
   /books/:
     post:
       summary: Creates a new book
       tags: [Books]
       requestBody:
         required: true
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/Book'
       responses:
         "200":
           description: The created book.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Book'
 /

让我们从Swagger标记开始进行部分分析。标签允许你在Swagger文档中创建一个部分。这意味着分配给该标签的所有路由都将显示在同一分区下。这是一个组织设置。

在我们的示例中, 所有端点都将映射到同一标签。

接下来, 是时候设置我们的第一个途径:这本书的创作。非常简单。首先, 定义标题并指定路径将要附加到的标签。

然后, 我们得到了请求和响应。在请求中, 定义三件事:定义是否需要请求, 请求的内容类型以及必须处理的模式。

可以通过以下方式引用架构:#components / schemas昂扬的运算符。

对于响应, 只需定义HTTP响应代码及其每个属性。目前, 我们只担心HTTP 200会带来幸福的道路。

继续并直接在Swagger UI页面中测试新操作:

显示Swagger运作方式的gif。

使用Swagger创建新书。

现在, 你可以看到示例值的位置。为你的用户提供示例数据以作为他们何时执行任务的参考更加容易。

在下面, 你可以找到所有其他操作的代码:

/
  @swagger
  path:
   /books/:
     get:
       summary: Lists all the books
       tags: [Books]
       responses:
         "200":
           description: The list of books.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Book'
     post:
       summary: Creates a new book
       tags: [Books]
       requestBody:
         required: true
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/Book'
       responses:
         "200":
           description: The created book.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Book'
   /books/{id}:
     get:
       summary: Gets a book by id
       tags: [Books]
       parameters:
         - in: path
           name: id
           schema:
             type: integer
           required: true
           description: The book id
       responses:
         "200":
           description: The list of books.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Book'
         "404":
           description: Book not found.
     put:
       summary: Updates a book
       tags: [Books]
       parameters:
         - in: path
           name: id
           schema:
             type: integer
           required: true
           description: The book id
       requestBody:
         required: true
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/Book'
       responses:
         "204":
           description: Update was successful.
         "404":
           description: Book not found.
     delete:
       summary: Deletes a book by id
       tags: [Books]
       parameters:
         - in: path
           name: id
           schema:
             type: integer
           required: true
           description: The book id
       responses:
         "204":
           description: Delete was successful.
         "404":
           description: Book not found.
 /

理想情况下, 这些映射应放在每个Express路由功能的上方。但是, 为了简单起见, 我们将它们集中在一个地方。

请注意, 我们将操作分为以下两个主要类别:

id

参数和没有的参数。

Swagger必须了解如何将路线与正确的路径参数匹配。

只要端点中有参数, 无论它们的类型如何, 都必须在parameters属性下通知详细信息。

所有端点正确映射的结果如下:

书籍API。

Swagger上的所有映射端点。

总结

你可以分别测试每个端点, 以确保其正常运行, 如Postman所要求的那样。

Swagger的功能不仅限于记录你的API。快速阅读官方文档将使你对其功能有更好的了解。请记住, 文档记录应该成为你团队文化的一部分。否则, 你的文档将不会总是最新的。

祝好运!

只有200 监视生产中失败和缓慢的网络请求

部署基于节点的Web应用程序或网站很容易。确保你的Node实例继续为你的应用程序提供资源是一件很困难的事情。如果你希望确保成功完成对后端或第三方服务的请求,

尝试notlogy

.

LogRocket网络请求监控

https://notlogy.com/signup/

日志火箭就像Web应用程序的DVR一样, 实际上记录了你网站上发生的一切。无需猜测问题发生的原因, 你可以汇总并报告有问题的网络请求, 以快速了解根本原因。

notlogy用你的应用程序记录基线性能计时, 例如页面加载时间, 到第一个字节的时间, 缓慢的网络请求, 并记录Redux, NgRx和Vuex的操作/状态。

免费开始监控

.

一盏木

发表评论

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen: