如何在 RESTful API 设计中使用 Swagger-UI 实现在线调试

如何在 RESTful API 设计中使用 Swagger-UI 实现在线调试

随着前端技术的不断发展和互联网的不断普及，RESTful API 已成为 web 开发的重要组成部分，而 Swagger-UI 作为一种可视化 RESTful API 接口文档工具，不仅可以帮助开发者清晰地了解 API 的使用方法和参数，还能快速实现 API 的在线调试，提高开发效率和质量。本文将详细介绍如何在 RESTful API 设计中使用 Swagger-UI 实现在线调试。

一、什么是 Swagger-UI

Swagger-UI 是 Swagger 平台中的一部分，为 RESTful API 接口文档的可视化展示工具，用于调试接口和生成客户端 SDK。Swagger-UI 的主要功能包括：

  1. 展示接口的基本信息，如名称、作者、描述等；
  2. 显示接口的请求和响应消息体、请求和响应头、错误码等信息；
  3. 支持在线测试和调试接口。

Swagger-UI 通过自动生成的接口文档，使得开发者更加了解每个接口的用途、参数、请求方式等详细信息，从而可以减少接口调用错误，提高开发效率和质量。

二、如何使用 Swagger-UI

实现基于 Swagger-UI 的在线调试需要以下步骤：

  1. 在 RESTful API 设计时使用 Swagger 规范，为接口添加注释；
  2. 安装 Swagger-UI；
  3. 将 RESTful API 接口文档导入 Swagger-UI 中；
  4. 进行在线测试和调试。

下面我们将详细介绍每个步骤的具体实现。

2.1 使用 Swagger 规范

在 RESTful API 设计中使用 Swagger 规范，是实现在线调试的关键步骤之一。Swagger 规范通过 YAML 或 JSON 格式的文档描述 API 的各种信息，包括接口名称、请求方式、请求参数、响应体等。以下是一份标准的 Swagger API 规范样本：

swagger: '2.0'
info:
  version: 1.0.0
  title: Swagger Petstore
  description: A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification
  contact:
    name: Swagger API Team
    email: apiteam@swagger.io
    url: 'http://swagger.io'
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
host: petstore.swagger.io
basePath: /v2
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
paths:
  /pet:
    post:
      summary: Add a new pet to the store
      operationId: addPet
      tags:
        - pet
      responses:
        '405':
          description: Invalid input
      parameters:
        - in: body
          name: body
          description: Pet object that needs to be added to the store
          required: true
          schema:
            $ref: '#/definitions/Pet'
  /pet/{petId}:
    get:
      summary: Find pet by ID
      description: Returns a single pet
      operationId: getPetById
      tags:
        - pet
      produces:
        - application/json
      parameters:
        - name: petId
          in: path
          description: ID of pet to return
          required: true
          type: integer
          format: int64
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/Pet'
        '400':
          description: Invalid ID supplied
        '404':
          description: Pet not found
    delete:
      summary: Deletes a pet
      description: ''
      operationId: deletePet
      tags:
        - pet
      parameters:
        - name: api_key
          in: header
          required: false
          type: string
      responses:
        '400':
          description: Invalid ID supplied
        '404':
          description: Pet not found
definitions:
  Pet:
    type: object
    required:
      - name
      - photoUrls
    properties:
      id:
        type: integer
        format: int64
      category:
        $ref: '#/definitions/Category'
      name:
        type: string
        example: doggie
      photoUrls:
        type: array
        xml:
          name: photoUrl
          wrapped: true
        items:
          type: string
      tags:
        $ref: '#/definitions/Tag'
      status:
        type: string
        description: pet status in the store
        enum:
          - available
          - pending
          - sold
  Category:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
  Tag:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string

上述样本中，定义了一个 PetStore 的接口文档，包括了 host、basePath、schemes、paths、definitions 等多个字段，每个字段定义了 RESTful API 接口必要的信息。

2.2 安装 Swagger-UI

安装 Swagger-UI 可以通过 npm 或直接下载源码的方式进行，这里以 npm 安装为例：

npm install -g swagger-ui

安装完成后，通过以下命令开启 Swagger-UI，将会监听默认的 8080 端口：

swagger-ui

启动成功后，通过浏览器输入 http://localhost:8080/ 即可进入 Swagger-UI 的首页。

2.3 将 RESTful API 接口文档导入 Swagger-UI 中

将 RESTful API 接口文档导入 Swagger-UI 主要有两种方式：

  1. 将 Swagger 规范文档集成到 RESTful API 的项目源代码中，然后将文档路径放到 Swagger-UI 的 index.html 中；
  2. 直接将 Swagger 规范文档通过 http 请求传递给 Swagger-UI。

这里我们选择第二种方式进行配置。可以手动编写一个 index.html，引入 Swagger-UI 的相关资源，然后在 index.html 中配置 Swagger 规范文档的路径。

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8"/>
    <title>Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="./swagger-ui.css"/>
    <link rel="stylesheet" type="text/css" href="./customize.css"/>
    <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
    <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
    <style>
      html
      {
        box-sizing: border-box;
        overflow: -moz-scrollbars-vertical;
        overflow-y: scroll;
      }
      *,
      *:before,
      *:after
      {
        box-sizing: inherit;
      }
    </style>
  </head>
  <body>
    <div id="swagger-ui"></div>

    <script src="./swagger-ui-bundle.js"></script>
    <script src="./swagger-ui-standalone-preset.js"></script>
    <script>
      window.onload = function() {
        // Build a system
        const ui = SwaggerUIBundle({
          url: "http://petstore.swagger.io/v2/swagger.json",
          dom_id: '#swagger-ui',
          presets: [
            SwaggerUIBundle.presets.apis,
            SwaggerUIStandalonePreset
          ],
          layout: "StandaloneLayout"
        })
      }
    </script>
  </body>
</html>

2.4 进行在线测试和调试

将 RESTful API 接口文档导入 Swagger-UI 成功后，在浏览器中输入地址 http://localhost:8080/ 即可访问 Swagger-UI 的主页，从而开始在线测试和调试。

首先，我们需要从接口列表中选择一个要测试的接口，然后单击该接口的名称，即可进入该接口的测试页面。测试页面会显示该接口的基本信息，包括 API 名称、请求方法、请求 URL、请求头等信息。

接下来，我们可以在测试页面上填写请求参数，然后单击测试按钮，即可进行接口的测试。测试页面会显示该接口的响应内容和响应状态码等信息，开发者可以根据响应内容和状态码来判断接口是否调用成功。

三、总结

Swagger-UI 是一种非常优秀的 RESTful API 可视化工具，它可以帮助我们快速构建文档和在线调试界面。通过本文的介绍，相信大家已经掌握了如何在 RESTful API 设计中使用 Swagger-UI 实现在线调试的方法，包括安装 Swagger-UI、将接口文档导入 Swagger-UI 中以及进行在线测试和调试等步骤。希望本文能为大家在使用 Swagger-UI 进行 RESTful API 接口开发中提供帮助。

来源：JavaScript中文网 ，转载请注明来源 本文地址：https://www.javascriptcn.com/post/659669fbeb4cecbf2da3d324

阅读全文

纠错反馈

精选内容

相关推荐

    暂无