首页手记 Swagger项目实战：新手入门指南

Swagger项目实战：新手入门指南

标签：

自动化测试接口测试 API

概述

本文详细介绍了如何在实际项目中应用Swagger，涵盖了从项目初始化到高级用法的全过程。通过定义API路径、操作及数据模型，实现安全认证，并使用标签和分组组织文档，最终确保API的高效开发和维护。Swagger项目实战包括了从理论到实践的迁移过程，帮助开发人员更好地理解和使用Swagger。Swagger项目实战内容丰富，涵盖了多个实战案例和详细步骤。

引入Swagger

什么是Swagger

Swagger 是一个用于设计、构建、文档化和使用 RESTful Web 服务的框架。它提供了一组工具，可以帮助开发者定义、生成、测试和使用 RESTful API。Swagger 使得 API 的描述和使用变得更加简便和标准化，从而促进了开发者之间的协作和 API 的互操作性。

Swagger 主要包括以下几个核心部分：

Swagger Specification（OpenAPI 规范）：定义了描述 RESTful API 的标准语法和格式。
Swagger Editor：一个在线编辑器，允许开发者编写和修改 API 文档。
Swagger UI：一个可嵌入的 Web 应用程序，用于展示和测试 API。
Swagger Codegen：自动生成客户端代码、服务器端代码和 API 文档。

Swagger 的优点和应用场景

优点

标准化：Swagger 规范使得 API 描述标准化，任何遵循该规范的工具都能理解和使用这些 API。
可读性：Swagger 生成的文档非常清晰易懂，开发人员可以轻松地阅读和理解 API。
自动生成客户端代码：Swagger Codegen 工具可以根据 API 文档自动生成客户端代码，大大减少了代码编写的工作量。
交互式测试：Swagger UI 提供了一个交互式的测试环境，开发人员可以直接在浏览器中测试 API。
版本控制：Swagger 支持版本控制，可以通过不同的版本号来管理不同的 API 版本。

应用场景

API 文档生成：Swagger 可以自动生成 API 文档，提高文档的准确性和一致性。
API 测试：通过 Swagger UI，可以在浏览器中测试 API，验证其功能和性能。
API 管理：Swagger 提供了一套完整的 API 管理工具，可以帮助团队更好地协作和管理 API。
API 互操作性：遵循 Swagger 规范的 API 可以在不同的系统和平台之间相互操作，促进不同系统之间的集成。
API 客户端生成：Swagger Codegen 可以根据 API 文档自动生成客户端代码，简化了客户端开发工作。

如何选择适合的 Swagger 版本

Swagger 提供了多个版本，每个版本都有不同的特性和改进。目前最常用的版本是 Swagger 2.0 和 OpenAPI 3.0。

Swagger 2.0

优点：规范成熟，社区支持广泛，工具链丰富。
缺点：某些功能不够强大，如对复杂的数据模型支持不足。

OpenAPI 3.0

优点：引入了更多的改进和增强功能，如更好的数据模型支持、独立的版本控制、更好地支持 OAuth 2.0 和 OpenID Connect。
缺点：新版本，可能存在一些兼容性问题。

选择适合的 Swagger 版本时，需要根据项目的需求和现有生态系统选择合适的版本。例如，如果项目需要支持更复杂的 API 架构和更丰富的数据模型，建议选择 OpenAPI 3.0。如果项目已经具有成熟的 Swagger 2.0 生态系统，可以继续使用 Swagger 2.0。

快速上手 Swagger

安装和配置 Swagger

为了快速上手 Swagger，我们首先需要设置开发环境并安装必要的工具。

安装 Swagger Editor

Swagger Editor 是一个在线编辑器，用于编写和修改 API 文档。它可以帮助我们验证和调试 Swagger 文档。以下是安装步骤：

打开浏览器，访问 Swagger Editor 在线版本。
如果您需要离线使用，可以下载源代码并在本地运行。

git clone https://github.com/swagger-api/swagger-editor.git
cd swagger-editor
npm install
npm start

安装 Swagger UI

Swagger UI 是一个可嵌入的 Web 应用程序，用于展示和测试 API。以下是安装步骤：

在本地安装 Node.js。
使用 npm 安装 Swagger UI：
```
npm install -g @swaggest/swagger-ui
```

安装 Swagger Codegen

Swagger Codegen 是一个自动生成客户端代码、服务端代码和 REST API 文档的工具。以下是安装步骤：

使用 npm 安装 Swagger Codegen：
```
npm install -g swagger-codegen
```

配置 Swagger

创建一个新的 Swagger API 文档文件，通常命名为 swagger.yaml 或 swagger.json。
在文档文件中编写 API 的基本信息，例如基本信息、路径、操作等。

swagger: '2.0'
info:
  version: '1.0.0'
  title: My Swagger API
  description: This is a simple example of a Swagger API.
host: localhost:8080
basePath: /api
schemes:
  - http
  - https
paths: {}

这个示例定义了一个基本的 Swagger 文档，包括基本信息、版本号、标题和描述、基础路径等。

初始化 Swagger 项目

初始化 Swagger 项目主要包括创建项目目录结构和配置 Swagger 文档文件。

创建项目目录结构

创建一个项目目录，例如 my-swagger-project，并在此目录中创建以下子目录：

docs：用于存储 Swagger API 文档文件。
src：用于存储源代码。
dist：用于存储生成的客户端代码或文档。

配置 Swagger 文档文件

在 docs 目录中创建一个 swagger.yaml 文件，并编写基本的 Swagger 文档结构：

swagger: '2.0'
info:
  version: '1.0.0'
  title: My Swagger API
  description: This is a simple example of a Swagger API.
host: localhost:8080
basePath: /api
schemes:
  - http
  - https
paths: {}

这个示例定义了一个基本的 Swagger 文档，包括基本信息、版本号、标题和描述、基础路径等。

创建第一个 Swagger 文档

在 swagger.yaml 文件中添加一个基本的 API 路径和操作。

添加一个 GET 操作

在 paths 下添加一个 GET 操作，例如获取用户列表：

paths:
  /users:
    get:
      summary: Get list of users
      description: Returns a list of users.
      responses:
        200:
          description: A list of users.
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
      email:
        type: string

添加一个 POST 操作

在 paths 下添加一个 POST 操作，例如创建用户：

paths:
  /users:
    post:
      summary: Create a new user
      description: Creates a new user.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: user
          description: User object to create.
          required: true
          schema:
            $ref: '#/definitions/User'
      responses:
        201:
          description: User created successfully.
          schema:
            $ref: '#/definitions/User'

生成 Swagger UI

使用 Swagger Codegen 生成 Swagger UI：

swagger-codegen generate \
  -i docs/swagger.yaml \
  -l swagger-ui \
  -o dist/swagger-ui

此命令将根据 swagger.yaml 文件生成 Swagger UI 并输出到 dist/swagger-ui 目录。

基本API文档编写

定义资源（Resource）和资源路径

资源是指 API 中的具体数据对象，例如用户、文章、评论等。资源路径是指访问这些资源的 URL 路径。

定义资源路径

在 swagger.yaml 文件中的 paths 字段下定义资源路径。例如，定义一个用户资源路径：

paths:
  /users:
    get:
      summary: Get list of users
      description: Returns a list of users.
      responses:
        200:
          description: A list of users.
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
  /users/{id}:
    get:
      summary: Get a user by ID
      description: Returns a user by ID.
      parameters:
        - name: id
          in: path
          required: true
          type: integer
          format: int64
      responses:
        200:
          description: User found.
          schema:
            $ref: '#/definitions/User'
  /users:
    post:
      summary: Create a new user
      description: Creates a new user.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: user
          description: User object to create.
          required: true
          schema:
            $ref: '#/definitions/User'
      responses:
        201:
          description: User created successfully.
          schema:
            $ref: '#/definitions/User'

定义资源模型

在 definitions 字段下定义资源模型，例如用户模型：

definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
      email:
        type: string

添加请求方法（GET, POST等）

请求方法定义了如何访问资源。常见的请求方法有 GET、POST、PUT、DELETE 等。

添加 GET 请求方法

添加一个 GET 请求方法，例如获取所有用户：

paths:
  /users:
    get:
      summary: Get list of users
      description: Returns a list of users.
      responses:
        200:
          description: A list of users.
          schema:
            type: array
            items:
              $ref: '#/definitions/User'

添加 POST 请求方法

添加一个 POST 请求方法，例如创建用户：

paths:
  /users:
    post:
      summary: Create a new user
      description: Creates a new user.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: user
          description: User object to create.
          required: true
          schema:
            $ref: '#/definitions/User'
      responses:
        201:
          description: User created successfully.
          schema:
            $ref: '#/definitions/User'

添加 PUT 请求方法

添加一个 PUT 请求方法，例如更新用户：

paths:
  /users/{id}:
    put:
      summary: Update a user by ID
      description: Updates a user by ID.
      parameters:
        - name: id
          in: path
          required: true
          type: integer
          format: int64
        - in: body
          name: user
          description: User object to update.
          required: true
          schema:
            $ref: '#/definitions/User'
      responses:
        200:
          description: User updated successfully.
          schema:
            $ref: '#/definitions/User'
        404:
          description: User not found.

添加 DELETE 请求方法

添加一个 DELETE 请求方法，例如删除用户：

paths:
  /users/{id}:
    delete:
      summary: Delete a user by ID
      description: Deletes a user by ID.
      parameters:
        - name: id
          in: path
          required: true
          type: integer
          format: int64
      responses:
        204:
          description: User deleted successfully.
        404:
          description: User not found.

描述响应和参数

描述响应

响应描述了 API 调用的结果。每个响应都包含状态码和响应体。

描述参数

参数描述了请求中可能包含的各种参数，例如路径参数、查询参数、请求体参数等。

描述响应示例

paths:
  /users:
    get:
      summary: Get list of users
      description: Returns a list of users.
      responses:
        200:
          description: A list of users.
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
        404:
          description: No users found.
        500:
          description: Internal server error.

描述参数示例

paths:
  /users/{id}:
    get:
      summary: Get a user by ID
      description: Returns a user by ID.
      parameters:
        - name: id
          in: path
          required: true
          type: integer
          format: int64
      responses:
        200:
          description: User found.
          schema:
            $ref: '#/definitions/User'
        404:
          description: User not found.

请求体示例

paths:
  /users:
    post:
      summary: Create a new user
      description: Creates a new user.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: user
          description: User object to create.
          required: true
          schema:
            $ref: '#/definitions/User'
      responses:
        201:
          description: User created successfully.
          schema:
            $ref: '#/definitions/User'
        400:
          description: Invalid input.

高级用法介绍

数据模型定义

定义数据模型

在 Swagger API 文档中，可以定义各种数据模型，例如用户、文章、评论等。

定义用户模型

definitions:
  User:
  type: object
  properties:
    id:
      type: integer
      format: int64
    name:
      type: string
    email:
      type: string

使用数据模型

在路径操作中引用定义的数据模型：

paths:
  /users:
    post:
      summary: Create a new user
      description: Creates a new user.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: user
          description: User object to create.
          required: true
          schema:
            $ref: '#/definitions/User'
      responses:
        201:
          description: User created successfully.
          schema:
            $ref: '#/definitions/User'

安全认证的实现

实现 Basic 认证

在 Swagger 文档中定义 Basic 认证：

securityDefinitions:
  basicAuth:
    type: basic
    description: Basic HTTP Authentication

使用 Basic 认证：

paths:
  /private:
    get:
      summary: Get private data
      description: Returns private data.
      security:
        - basicAuth: []
      responses:
        200:
          description: Private data.
          schema:
            type: string

实现 API Key 认证

在 Swagger 文档中定义 API Key 认证：

securityDefinitions:
  apiKey:
    type: apiKey
    name: api_key
    in: query

使用 API Key 认证：

paths:
  /private:
    get:
      summary: Get private data
      description: Returns private data.
      security:
        - apiKey: []
      responses:
        200:
          description: Private data.
          schema:
            type: string

实现 OAuth 2.0 认证

在 Swagger 文档中定义 OAuth 2.0 认证：

securityDefinitions:
  oauth2:
    type: oauth2
    flow: application
    authorizationUrl: https://example.com/oauth2/authorize
    tokenUrl: https://example.com/oauth2/token
    scopes:
      read: Read all data
      write: Write all data

使用 OAuth 2.0 认证：

paths:
  /private:
    get:
      summary: Get private data
      description: Returns private data.
      security:
        - oauth2:
            - read
            - write
      responses:
        200:
          description: Private data.
          schema:
            type: string

使用标签和分组组织文档

使用标签组织文档

标签可以用来组织和分类不同的 API 路径。

tags:
  - name: User
    description: Operations on user data.
  - name: Article
    description: Operations on article data.

使用标签：

paths:
  /users:
    get:
      tags:
        - User
      summary: Get list of users
      description: Returns a list of users.
      responses:
        200:
          description: A list of users.
          schema:
            type: array
            items:
              $ref: '#/definitions/User'

使用分组组织文档

分组可以用来组织不同的 API 版本或不同的服务。

x-openapi-router:
  path: /api/v1
  paths:
    /users:
      get:
        tags:
          - User
        summary: Get list of users
        description: Returns a list of users.
        responses:
          200:
            description: A list of users.
            schema:
              type: array
              items:
                $ref: '#/definitions/User'

测试和调试 Swagger 文档

使用 Swagger UI 进行测试

部署 Swagger UI

将生成的 Swagger UI 文件部署到 Web 服务器，例如 Apache 或 Nginx。

swagger-codegen generate \
  -i docs/swagger.yaml \
  -l swagger-ui \
  -o dist/swagger-ui

启动 Web 服务器：

sudo service apache2 start

访问 Swagger UI

在浏览器中访问部署的 Swagger UI 地址，例如 http://localhost/swagger-ui/。

测试 API

在 Swagger UI 中选择需要测试的 API 路径，填写请求参数，点击 Try it out 按钮进行测试。

调试常见问题和解决方法

问题：请求失败

解决方法

检查请求 URL 是否正确。
检查请求方法（GET、POST 等）是否正确。
检查请求参数是否正确。
检查请求头是否正确。

问题：响应不符合预期

解决方法

检查请求参数是否正确。
检查 API 路径是否正确。
检查 API 路径是否存在。
检查 API 版本是否正确。
检查 API 文档是否正确。

问题：Swagger UI 无法加载

解决方法

检查 Swagger UI 文件是否正确生成。
检查 Web 服务器是否正确配置。
检查 Web 服务器是否启动。
检查 Swagger UI URL 是否正确。

问题：响应时间过长

解决方法

检查服务器性能。
检查服务器负载。
检查网络延迟。
检查 API 逻辑是否复杂。
检查数据库查询是否优化。

实战案例分析

分析实际项目中的 Swagger 应用

示例项目结构

假设我们有一个博客应用，包含以下几个 API：

获取文章列表
获取文章详情
创建文章
更新文章
删除文章
获取用户列表
获取用户详情
创建用户
更新用户
删除用户

Swagger 文档示例

以下是一个简单的 Swagger 文档示例，展示了如何定义这些 API：

swagger: '2.0'
info:
  version: '1.0.0'
  title: Blog API
  description: This is a simple example of a blog API.
host: localhost:8080
basePath: /api
schemes:
  - http
  - https
paths:
  /articles:
    get:
      summary: Get list of articles
      description: Returns a list of articles.
      responses:
        200:
          description: A list of articles.
          schema:
            type: array
            items:
              $ref: '#/definitions/Article'
  /articles/{id}:
    get:
      summary: Get an article by ID
      description: Returns an article by ID.
      parameters:
        - name: id
          in: path
          required: true
          type: integer
          format: int64
      responses:
        200:
          description: Article found.
          schema:
            $ref: '#/definitions/Article'
        404:
          description: Article not found.
  /articles:
    post:
      summary: Create a new article
      description: Creates a new article.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: article
          description: Article object to create.
          required: true
          schema:
            $ref: '#/definitions/Article'
      responses:
        201:
          description: Article created successfully.
          schema:
            $ref: '#/definitions/Article'
        400:
          description: Invalid input.
  /articles/{id}:
    put:
      summary: Update an article by ID
      description: Updates an article by ID.
      parameters:
        - name: id
          in: path
          required: true
          type: integer
          format: int64
        - in: body
          name: article
          description: Article object to update.
          required: true
          schema:
            $ref: '#/definitions/Article'
      responses:
        200:
          description: Article updated successfully.
          schema:
            $ref: '#/definitions/Article'
        404:
          description: Article not found.
  /articles/{id}:
    delete:
      summary: Delete an article by ID
      description: Deletes an article by ID.
      parameters:
        - name: id
          in: path
          required: true
          type: integer
          format: int64
      responses:
        204:
          description: Article deleted successfully.
        404:
          description: Article not found.
  /users:
    get:
      summary: Get list of users
      description: Returns a list of users.
      responses:
        200:
          description: A list of users.
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
  /users/{id}:
    get:
      summary: Get a user by ID
      description: Returns a user by ID.
      parameters:
        - name: id
          in: path
          required: true
          type: integer
          format: int64
      responses:
        200:
          description: User found.
          schema:
            $ref: '#/definitions/User'
        404:
          description: User not found.
  /users:
    post:
      summary: Create a new user
      description: Creates a new user.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: user
          description: User object to create.
          required: true
          schema:
            $ref: '#/definitions/User'
      responses:
        201:
          description: User created successfully.
          schema:
            $ref: '#/definitions/User'
        400:
          description: Invalid input.
  /users/{id}:
    put:
      summary: Update a user by ID
      description: Updates a user by ID.
      parameters:
        - name: id
          in: path
          required: true
          type: integer
          format: int64
        - in: body
          name: user
          description: User object to update.
          required: true
          schema:
            $ref: '#/definitions/User'
      responses:
        200:
          description: User updated successfully.
          schema:
            $ref: '#/definitions/User'
        404:
          description: User not found.
  /users/{id}:
    delete:
      summary: Delete a user by ID
      description: Deletes a user by ID.
      parameters:
        - name: id
          in: path
          required: true
          type: integer
          format: int64
      responses:
        204:
          description: User deleted successfully.
        404:
          description: User not found.
definitions:
  Article:
    type: object
    properties:
      id:
        type: integer
        format: int64
      title:
        type: string
      content:
        type: string
      author:
        type: string
  User:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
      email:
        type: string

从理论到实践的迁移过程

定义 API 路径和操作：根据项目需求定义 API 路径和操作，例如 GET、POST、PUT、DELETE 等。
定义数据模型：定义 API 中使用的数据模型，例如文章、用户等。
编写 Swagger 文档：使用 Swagger 格式编写 API 文档，包括路径、操作、响应、参数等。
生成 Swagger UI：使用 Swagger Codegen 生成 Swagger UI，并部署到 Web 服务器。
测试和调试：使用 Swagger UI 测试 API，调试常见问题和解决方法。
部署 API 服务：将编写好的 API 服务部署到服务器，并使用 Swagger 文档进行管理和维护。

示例代码

以下是一个简单的示例代码，展示了如何使用 Swagger API 文档定义一个简单的 API 服务：

from flask import Flask, jsonify, request
from flask_restful import Resource, Api

app = Flask(__name__)
api = Api(app)

articles = [
    {
        "id": 1,
        "title": "文章一",
        "content": "文章一的内容",
        "author": "作者一"
    },
    {
        "id": 2,
        "title": "文章二",
        "content": "文章二的内容",
        "author": "作者二"
    }
]

class Article(Resource):
    def get(self, article_id=None):
        if article_id:
            article = next((article for article in articles if article['id'] == article_id), None)
            if article:
                return article
            return {"message": "文章未找到"}, 404
        return articles

    def post(self):
        data = request.get_json()
        article = {
            "id": len(articles) + 1,
            "title": data.get('title'),
            "content": data.get('content'),
            "author": data.get('author')
        }
        articles.append(article)
        return article, 201

    def put(self, article_id):
        data = request.get_json()
        article = next((article for article in articles if article['id'] == article_id), None)
        if article:
            article['title'] = data.get('title')
            article['content'] = data.get('content')
            article['author'] = data.get('author')
            return article
        return {"message": "文章未找到"}, 404

    def delete(self, article_id):
        global articles
        articles = [article for article in articles if article['id'] != article_id]
        return {"message": "文章删除成功"}

api.add_resource(Article, '/articles', '/articles/<int:article_id>')

users = [
    {
        "id": 1,
        "name": "用户一",
        "email": "user1@example.com"
    },
    {
        "id": 2,
        "name": "用户二",
        "email": "user2@example.com"
    }
]

class User(Resource):
    def get(self, user_id=None):
        if user_id:
            user = next((user for user in users if user['id'] == user_id), None)
            if user:
                return user
            return {"message": "用户未找到"}, 404
        return users

    def post(self):
        data = request.get_json()
        user = {
            "id": len(users) + 1,
            "name": data.get('name'),
            "email": data.get('email')
        }
        users.append(user)
        return user, 201

    def put(self, user_id):
        data = request.get_json()
        user = next((user for user in users if user['id'] == user_id), None)
        if user:
            user['name'] = data.get('name')
            user['email'] = data.get('email')
            return user
        return {"message": "用户未找到"}, 404

    def delete(self, user_id):
        global users
        users = [user for user in users if user['id'] != user_id]
        return {"message": "用户删除成功"}

api.add_resource(User, '/users', '/users/<int:user_id>')

if __name__ == '__main__':
    app.run(debug=True)

实战案例总结

通过以上实战案例，我们可以看到 Swagger 在实际项目中的应用，包括定义 API 路径和操作、数据模型定义、安全认证实现、标签和分组组织文档等。这些步骤可以帮助我们更好地管理和维护 API 服务，提高开发效率和 API 的互操作性。

总结：

定义 API 路径和操作：根据项目需求定义 API 路径和操作，确保 API 的功能性和正确性。
数据模型定义：定义 API 中使用的数据模型，确保数据的一致性和标准化。
安全认证实现：实现各种安全认证，确保 API 的安全性。
标签和分组组织文档：使用标签和分组组织文档，提高文档的可读性和管理性。
测试和调试：使用 Swagger UI 测试 API，调试常见问题和解决方法，确保 API 的正确性和性能。
部署 API 服务：将编写好的 API 服务部署到服务器，并使用 Swagger 文档进行管理和维护。

通过这些步骤，我们可以更好地开发和维护 API 服务，提高开发效率和 API 的互操作性。

点击查看更多内容

为 TA 点赞

若觉得本文不错，就分享一下吧！

评论

评论

共同学习，写下你的评论

评论加载中...

展开查看更多评论

作者其他优质文章

正在加载中

吃鸡游戏

手记
篇

粉丝

55

获赞与收藏

339

关注作者，订阅最新文章

阅读免费教程

Hibernate 入门教程

29个小节 6360 93

HTTP 入门教程

28个小节 37784 648

后端通用面试教程

41个小节 30583 343

推荐

评论

收藏

共同学习，写下你的评论



感谢您的支持，我会继续努力的～

扫码打赏，你说多少就多少

赞赏金额会直接到老师账户

支付方式

打开微信扫一扫，即可进行扫码打赏哦

今天注册有机会得

100积分直接送

付费专栏免费学

大额优惠券免费领

立即参与放弃机会

点击
抽奖

慕课手记新用户专享福利

恭喜你，你的运气太好了，居然抽中了 100个积分！

恭喜你，抽中了价值元的专栏！

太棒了，直接落到你账户里！

积分商城里的罗技鼠标、机械键盘、
Kindle 阅读器、小米平衡车
Apple iPad （10.2英寸）、大额优惠券
在等着你去兑换了噢

作者：

免费赠送

兑换码：1111222211 复制

优惠券可用于购买实战课、体系课
无门槛使用

先去看看，有什么好东西马上兑换我爱学习，选课去


热搜

最近搜索清空

Swagger项目实战：新手入门指南

优点

应用场景

Swagger 2.0

OpenAPI 3.0

安装 Swagger Editor

安装 Swagger UI

安装 Swagger Codegen

配置 Swagger

创建项目目录结构

配置 Swagger 文档文件

添加一个 GET 操作

添加一个 POST 操作

生成 Swagger UI

定义资源路径

定义资源模型

添加 GET 请求方法

添加 POST 请求方法

添加 PUT 请求方法

添加 DELETE 请求方法

描述响应

描述参数

描述响应示例

描述参数示例

请求体示例

定义数据模型

定义用户模型

使用数据模型

实现 Basic 认证

实现 API Key 认证

实现 OAuth 2.0 认证

使用标签组织文档

使用分组组织文档

部署 Swagger UI

访问 Swagger UI

测试 API

问题：请求失败

解决方法

问题：响应不符合预期

解决方法

问题：Swagger UI 无法加载

解决方法

问题：响应时间过长

解决方法

示例项目结构

Swagger 文档示例

从理论到实践的迁移过程

示例代码

实战案例总结

阅读免费教程