叶哥Linux技术分享

主题

API文档和Swagger使用 ​

课程简介 ​

API文档是现代Web开发中不可或缺的一部分，它不仅是前后端开发人员之间的桥梁，也是API使用者了解和使用API的重要参考。本课程将详细介绍API文档的重要性、Swagger/OpenAPI规范的使用方法，以及如何在不同的Web框架中集成Swagger。

1. API文档的重要性 ​

1.1 为什么需要API文档 ​

  • 提高开发效率：减少前后端开发人员之间的沟通成本
  • 便于测试：测试人员可以根据文档进行API测试
  • 便于维护：新加入的开发人员可以快速了解API结构
  • 提高API质量：文档化过程迫使开发人员思考API设计
  • 便于集成：第三方开发者可以更容易地集成你的API

1.2 好的API文档应该包含什么 ​

  • API端点：URL路径、HTTP方法
  • 请求参数：查询参数、路径参数、请求体
  • 响应格式：成功响应、错误响应
  • 认证方式：API密钥、OAuth、JWT等
  • 示例代码：不同语言的调用示例
  • 错误码：常见错误码及其含义
  • 版本信息：API版本号及变更历史

2. Swagger/OpenAPI介绍 ​

2.1 什么是Swagger/OpenAPI ​

  • OpenAPI规范：前身为Swagger规范，是一种用于描述RESTful API的开放标准
  • Swagger工具集：包括Swagger Editor、Swagger UI、Swagger Codegen等工具
  • 版本演进：从Swagger 1.0到OpenAPI 3.0+

2.2 OpenAPI规范的核心概念 ​

  • Info：API的基本信息（标题、版本、描述等）
  • Paths：API端点定义
  • Schemas：数据模型定义
  • Parameters：参数定义
  • Responses：响应定义
  • Security：安全方案定义
  • Tags：API分组标签

3. 在Flask中集成Swagger ​

3.1 安装依赖 ​

bash
pip install flasgger

3.2 基本使用 ​

python
from flask import Flask, request, jsonify
from flasgger import Swagger, swag_from

app = Flask(__name__)
swagger = Swagger(app)

@app.route('/api/users', methods=['GET'])
def get_users():
    """
    获取用户列表
    ---
    tags:
      - 用户管理
    parameters:
      - name: page
        in: query
        type: integer
        required: false
        default: 1
        description: 页码
      - name: per_page
        in: query
        type: integer
        required: false
        default: 10
        description: 每页数量
    responses:
      200:
        description: 成功获取用户列表
        schema:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
            data:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: integer
                  username:
                    type: string
                  email:
                    type: string
    """
    page = request.args.get('page', 1, type=int)
    per_page = request.args.get('per_page', 10, type=int)
    
    # 模拟数据
    users = [
        {"id": 1, "username": "user1", "email": "user1@example.com"},
        {"id": 2, "username": "user2", "email": "user2@example.com"}
    ]
    
    return jsonify({
        "code": 200,
        "message": "success",
        "data": users
    })

@app.route('/api/users', methods=['POST'])
def create_user():
    """
    创建新用户
    ---
    tags:
      - 用户管理
    parameters:
      - name: user
        in: body
        required: true
        schema:
          type: object
          properties:
            username:
              type: string
              required: true
            email:
              type: string
              required: true
            password:
              type: string
              required: true
    responses:
      201:
        description: 用户创建成功
      400:
        description: 请求参数错误
    """
    user_data = request.get_json()
    
    if not user_data or not all(key in user_data for key in ['username', 'email', 'password']):
        return jsonify({"code": 400, "message": "参数错误"}), 400
    
    # 模拟创建用户
    return jsonify({"code": 201, "message": "用户创建成功", "data": {"id": 3, **user_data}}), 201

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

3.3 访问Swagger UI ​

启动应用后，访问 http://localhost:5000/apidocs/ 即可看到Swagger UI界面。

4. 在Django中集成Swagger ​

4.1 安装依赖 ​

bash
pip install drf-yasg

4.2 配置Django项目 ​

python
# settings.py
INSTALLED_APPS = [
    # ...
    'rest_framework',
    'drf_yasg',
]

# urls.py
from django.contrib import admin
from django.urls import path, include
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

SchemaView = get_schema_view(
   openapi.Info(
      title="API文档",
      default_version='v1',
      description="API接口文档",
      terms_of_service="https://www.example.com/policies/terms/",
      contact=openapi.Contact(email="contact@example.com"),
      license=openapi.License(name="BSD License"),
   ),
   public=True,
   permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('api.urls')),
    path('swagger<format>/', SchemaView.without_ui(cache_timeout=0), name='schema-json'),
    path('swagger/', SchemaView.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    path('redoc/', SchemaView.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
]

4.3 在视图中使用 ​

python
# api/views.py
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status
from drf_yasg import openapi
from drf_yasg.utils import swagger_auto_schema

class UserView(APIView):
    @swagger_auto_schema(
        operation_description="获取用户列表",
        tags=['用户管理'],
        manual_parameters=[
            openapi.Parameter('page', openapi.IN_QUERY, description="页码", type=openapi.TYPE_INTEGER),
            openapi.Parameter('per_page', openapi.IN_QUERY, description="每页数量", type=openapi.TYPE_INTEGER),
        ],
        responses={
            200: openapi.Response(
                description="成功获取用户列表",
                schema=openapi.Schema(
                    type=openapi.TYPE_OBJECT,
                    properties={
                        'code': openapi.Schema(type=openapi.TYPE_INTEGER),
                        'message': openapi.Schema(type=openapi.TYPE_STRING),
                        'data': openapi.Schema(
                            type=openapi.TYPE_ARRAY,
                            items=openapi.Schema(
                                type=openapi.TYPE_OBJECT,
                                properties={
                                    'id': openapi.Schema(type=openapi.TYPE_INTEGER),
                                    'username': openapi.Schema(type=openapi.TYPE_STRING),
                                    'email': openapi.Schema(type=openapi.TYPE_STRING),
                                }
                            )
                        )
                    }
                )
            )
        }
    )
    def get(self, request):
        page = request.query_params.get('page', 1, type=int)
        per_page = request.query_params.get('per_page', 10, type=int)
        
        # 模拟数据
        users = [
            {"id": 1, "username": "user1", "email": "user1@example.com"},
            {"id": 2, "username": "user2", "email": "user2@example.com"}
        ]
        
        return Response({
            "code": 200,
            "message": "success",
            "data": users
        })
    
    @swagger_auto_schema(
        operation_description="创建新用户",
        tags=['用户管理'],
        request_body=openapi.Schema(
            type=openapi.TYPE_OBJECT,
            required=['username', 'email', 'password'],
            properties={
                'username': openapi.Schema(type=openapi.TYPE_STRING),
                'email': openapi.Schema(type=openapi.TYPE_STRING),
                'password': openapi.Schema(type=openapi.TYPE_STRING),
            }
        ),
        responses={
            201: openapi.Response(description="用户创建成功"),
            400: openapi.Response(description="请求参数错误"),
        }
    )
    def post(self, request):
        user_data = request.data
        
        if not user_data or not all(key in user_data for key in ['username', 'email', 'password']):
            return Response({"code": 400, "message": "参数错误"}, status=status.HTTP_400_BAD_REQUEST)
        
        # 模拟创建用户
        return Response({"code": 201, "message": "用户创建成功", "data": {"id": 3, **user_data}}, status=status.HTTP_201_CREATED)

# api/urls.py
from django.urls import path
from .views import UserView

urlpatterns = [
    path('users/', UserView.as_view()),
]

4.4 访问Swagger UI ​

启动应用后，访问 http://localhost:8000/swagger/ 即可看到Swagger UI界面。

5. 在Gin中集成Swagger ​

5.1 安装依赖 ​

bash
go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
go get -u github.com/go-openapi/spec

5.2 生成Swagger文档 ​

首先，在代码中添加Swagger注释：

go
// main.go
package main

import (
    "net/http"
    "github.com/gin-gonic/gin"
    "github.com/swaggo/files"
    "github.com/swaggo/gin-swagger"
    _ "your-project/docs" // 导入生成的文档
)

// @title API文档
// @version 1.0
// @description API接口文档
// @termsOfService https://www.example.com/policies/terms/
// @contact.name API Support
// @contact.email contact@example.com
// @license.name BSD License
// @license.url https://opensource.org/licenses/BSD-3-Clause
// @host localhost:8080
// @BasePath /api
func main() {
    r := gin.Default()
    
    // 注册Swagger路由
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    
    // API路由组
    api := r.Group("/api")
    {
        users := api.Group("/users")
        {
            users.GET("", GetUsers)
            users.POST("", CreateUser)
        }
    }
    
    r.Run(":8080")
}

// GetUsers 获取用户列表
// @Summary 获取用户列表
// @Description 获取所有用户的列表
// @Tags 用户管理
// @Accept json
// @Produce json
// @Param page query int false "页码" default(1)
// @Param per_page query int false "每页数量" default(10)
// @Success 200 {object} map[string]interface{} "成功获取用户列表"
// @Router /api/users [get]
func GetUsers(c *gin.Context) {
    page := c.DefaultQuery("page", "1")
    perPage := c.DefaultQuery("per_page", "10")
    
    // 模拟数据
    users := []map[string]interface{}{
        {"id": 1, "username": "user1", "email": "user1@example.com"},
        {"id": 2, "username": "user2", "email": "user2@example.com"},
    }
    
    c.JSON(http.StatusOK, gin.H{
        "code": 200,
        "message": "success",
        "data": users,
    })
}

// UserCreate 用户创建请求
// @Description 用户创建请求结构
// @Tags 用户管理
type UserCreate struct {
    Username string `json:"username" binding:"required"`
    Email    string `json:"email" binding:"required,email"`
    Password string `json:"password" binding:"required"`
}

// CreateUser 创建新用户
// @Summary 创建新用户
// @Description 创建一个新的用户
// @Tags 用户管理
// @Accept json
// @Produce json
// @Param user body UserCreate true "用户信息"
// @Success 201 {object} map[string]interface{} "用户创建成功"
// @Failure 400 {object} map[string]interface{} "请求参数错误"
// @Router /api/users [post]
func CreateUser(c *gin.Context) {
    var user UserCreate
    if err := c.ShouldBindJSON(&user); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{
            "code": 400,
            "message": "参数错误",
        })
        return
    }
    
    // 模拟创建用户
    c.JSON(http.StatusCreated, gin.H{
        "code": 201,
        "message": "用户创建成功",
        "data": gin.H{
            "id": 3,
            "username": user.Username,
            "email": user.Email,
        },
    })
}

然后，生成Swagger文档：

bash
sweg init

5.3 访问Swagger UI ​

启动应用后，访问 http://localhost:8080/swagger/index.html 即可看到Swagger UI界面。

6. Swagger UI的使用 ​

6.1 浏览API文档 ​

  • API分组：通过Tags查看不同分组的API
  • API详情：点击API查看详细信息
  • 参数说明：查看请求参数和响应格式
  • 示例代码：查看不同语言的调用示例

6.2 测试API ​

  • 填写参数：在UI中填写请求参数
  • 发送请求：点击"Try it out"发送请求
  • 查看响应：实时查看API响应结果
  • 复制curl命令：复制生成的curl命令用于命令行测试

7. API测试和调试 ​

7.1 使用Swagger UI进行测试 ​

  1. 打开Swagger UI界面
  2. 选择要测试的API端点
  3. 点击"Try it out"按钮
  4. 填写必要的参数
  5. 点击"Execute"按钮发送请求
  6. 查看响应结果

7.2 使用Postman进行测试 ​

  1. 导入Swagger文档到Postman
  2. 选择要测试的API端点
  3. 填写请求参数
  4. 发送请求并查看响应
  5. 保存测试用例

7.3 使用curl命令进行测试 ​

bash
# 测试GET请求
curl -X GET "http://localhost:5000/api/users?page=1&per_page=10" -H "accept: application/json"

# 测试POST请求
curl -X POST "http://localhost:5000/api/users" \
  -H "Content-Type: application/json" \
  -d '{"username": "test", "email": "test@example.com", "password": "123456"}'

8. 最佳实践 ​

8.1 API文档设计最佳实践 ​

  • 保持文档与代码同步：使用工具自动生成文档
  • 提供详细的示例：包含请求和响应的完整示例
  • 使用一致的命名规范：API路径、参数名等使用一致的命名风格
  • 版本控制：在API路径中包含版本号
  • 错误处理：详细说明错误码和错误信息
  • 安全说明：包含认证方式和安全注意事项

8.2 Swagger使用最佳实践 ​

  • 使用Tags对API进行分组：提高文档的可读性
  • 添加详细的描述：对API、参数、响应等添加详细描述
  • 使用模型定义：对复杂的请求和响应结构使用模型定义
  • 提供默认值：为可选参数提供默认值
  • 使用枚举类型：对有限的取值范围使用枚举类型
  • 定期更新文档：确保文档与API实际行为一致

8.3 常见问题及解决方案 ​

  • 文档与代码不同步：使用自动化工具生成文档
  • 文档过于复杂：合理组织API分组，使用简洁的描述
  • 缺少示例：为每个API提供完整的请求和响应示例
  • 版本管理：在API路径和文档中明确版本信息
  • 安全问题：不要在文档中包含敏感信息

9. 总结 ​

本课程详细介绍了API文档的重要性、Swagger/OpenAPI规范的使用方法，以及如何在Flask、Django和Gin等不同的Web框架中集成Swagger。通过本课程的学习，你应该能够：

  1. 理解API文档在现代Web开发中的重要性
  2. 掌握Swagger/OpenAPI规范的基本概念
  3. 在不同的Web框架中集成Swagger
  4. 使用Swagger UI浏览和测试API
  5. 遵循API文档设计的最佳实践

API文档是API开发的重要组成部分，良好的API文档不仅可以提高开发效率，还可以提升API的可用性和可维护性。希望本课程能够帮助你在实际项目中更好地使用Swagger来管理和维护API文档。

思考与练习 ​

  1. 在你之前创建的Flask、Django或Gin项目中集成Swagger
  2. 为一个完整的用户管理API设计Swagger文档
  3. 使用Swagger UI测试你设计的API
  4. 比较不同框架中Swagger集成的异同
  5. 思考如何在团队开发中保持API文档的同步更新

通过实际的练习，你将更深入地理解Swagger的使用方法，以及如何创建高质量的API文档。

评论区

专业的Linux技术学习平台，从入门到精通的完整学习路径

Copyright © 2026 叶哥Linux技术分享 - linuxeasy.site