代码注释是 “ 给未来的自己和同事看 ” ，核心是 “ 说明‘为什么这么写’+ ‘怎么用’ ” 。API 文档是 “ 给调用者看 ” ，核心是 “ 说明‘接口怎么调’+ ‘参数/ 响应是什么’ ” 。

代码注释与API 文档是代码可维护性与可复用性的核心。传统模式下，开发人员常因时间紧张导致注释缺失、文档不规范，影响后续维护与协作。千问可自动生成代码注释（单行注释、函数注释、类注释）与标准化API 文档（如Swagger 风格），确保代码可读性与文档规范性。

示例：生成代码注释和API 文档

某公司后端团队正在开发一个基于Flask 的用户登录接口。开发人员小张完成了核心逻辑，但尚未添加注释和文档。该接口接收POST 请求，参数为username （必填）、password （必填）、captcha （可选），成功后返回JWT 令牌。按照公司规范，他需要在今天下班前提交符合PEP8 标准的代码注释和一份可用于Swagger 的API 文档。但他正忙于修复另一个紧急bug ，急需一个工具能帮他快速生成初稿。

在代码对话框中输入如下提示词：

你是一名技术文档工程师，请为以下任务生成规范文档：

【任务类型】 Python 代码注释生成 +RESTful API 文档生成

【核心信息】

- 功能描述：用户登录认证

- 代码 / 接口详情：

- 请求方式： POST

- 接口路径： /api/v1/login

- 参数： username (str, 必填 ), password (str, 必填 ), captcha (str, 可选 )

- 响应： JSON ，成功时包含 code=200, message, data(token, expire_time, username)

【输出要求】

1. 代码注释：符合 Python PEP8 规范，包含功能、参数、返回值、异常、备注。

2. API 文档：包含接口路径、请求方法、参数详情、响应示例、错误码说明。

3. 格式清晰，支持直接复制到代码 /Swagger 。

输出结果如下：

Flask 用户登录接口：

"""

@Author: 技术文档助手

@Version: 1.0

@Description: 用户登录认证接口模块，负责验证用户身份合法性，返回认证令牌

@Date: 2025-01-20

"""

from flask import Flask, request, jsonify

import jwt

import datetime

app = Flask(__name__)

app.config['SECRET_KEY'] = 'your-secret-key' # 实际生产环境需使用环境变量存储

def verify_password(username: str, password: str) -> bool:

"""

验证用户名与密码合法性（模拟数据库校验逻辑）

Args:

username: 用户名（字符串，长度 6-20 位，仅含字母 / 数字）

password: 密码（字符串，长度 8-20 位，含字母 + 数字 + 特殊字符）

Returns:

bool: 验证通过返回 True ，否则返回 False

Notes:

实际场景需对接数据库查询，此处为简化模拟；

生产环境需使用密码哈希校验（如 bcrypt ），禁止明文比对

"""

# 模拟数据库存储的用户名与加密后密码（示例数据）

mock_users = {

"test_user": "$2b$12$EixZaYb4xU58Gpq1R0yWbeb00LU5qUaK6x6hTOj0K2qCk2aK6z2a" # 密码： Test@1234

}

if username not in mock_users:

return False

# 模拟哈希密码校验（实际需用 bcrypt.checkpw(password.encode(), mock_users[username].encode()) ）

return password == "Test@1234"

@app.route('/api/v1/login', methods=['POST'])

def user_login():

"""

用户登录认证接口：验证用户身份并生成 JWT 令牌

Request:

Content-Type: application/json

Body: {

"username": string, // 用户名（必填）

"password": string, // 密码（必填）

"captcha": string // 验证码（可选，生产环境建议必填）

}

Response:

200 OK: {

"code": 200,

"message": " 登录成功 ",

"data": {

"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // JWT 令牌（有效期 2 小时）

"expire_time": "2025-01-20T16:30:00Z",

"username": "test_user"

}

400 Bad Request: {

"code": 400,

"message": " 参数缺失：用户名不能为空 "

}

401 Unauthorized: {

"code": 401,

"message": " 用户名或密码错误 "

}

Errors:

400: 参数缺失 / 格式错误

401: 身份验证失败

500: 服务器内部错误

Notes:

1. JWT 令牌有效期 2 小时，过期需重新登录；

2. 验证码功能需对接第三方验证码服务（如极验），此处简化省略；

3. 生产环境需添加 HTTPS 加密传输，避免密码泄露

"""

try:

data = request.get_json()

# 参数校验

if not data.get("username"):

return jsonify({"code": 400, "message": " 参数缺失：用户名不能为空 "}), 400

if not data.get("password"):

return jsonify({"code": 400, "message": " 参数缺失：密码不能为空 "}), 400

# 密码验证

if not verify_password(data["username"], data["password"]):

return jsonify({"code": 401, "message": " 用户名或密码错误 "}), 401

# 生成 JWT 令牌

expire = datetime.datetime.utcnow() + datetime.timedelta(hours=2)

token = jwt.encode(

{"username": data["username"], "exp": expire},

app.config['SECRET_KEY'],

algorithm="HS256"

)

return jsonify({

"code": 200,

"message": " 登录成功 ",

"data": {

"token": token,

"expire_time": expire.isoformat() + "Z",

"username": data["username"]

}

}), 200

except Exception as e:

return jsonify({"code": 500, "message": f" 服务器内部错误： {str(e)}"}), 500

if __name__ == "__main__":

app.run(debug=True, host="0.0.0.0", port=5000)

OpenAPI 3.0 用户文档认证API 文档：

openapi: 3.0.3

info:

title: 用户认证 API

description: 提供用户登录、令牌验证等认证相关接口

version: 1.0.0

paths:

/api/v1/login:

post:

summary: 用户登录认证

description: 验证用户用户名和密码，生成有效期 2 小时的 JWT 令牌

requestBody:

required: true

content:

application/json:

schema:

type: object

properties:

username:

type: string

description: 用户名（ 6-20 位，仅含字母 / 数字）

example: "test_user"

password:

type: string

description: 密码（ 8-20 位，含字母 + 数字 + 特殊字符）

example: "Test@1234"

captcha:

type: string

description: 验证码（可选，生产环境建议必填）

example: "8F3D2A"

required:

- username

- password

responses:

'200':

description: 登录成功

content:

application/json:

schema:

type: object

properties:

code:

type: integer

example: 200

message:

type: string

example: " 登录成功 "

data:

type: object

properties:

token:

type: string

example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

expire_time:

type: string

format: date-time

example: "2025-01-20T16:30:00Z"

username:

type: string

example: "test_user"

'400':

description: 参数缺失或格式错误

content:

application/json:

schema:

type: object

properties:

code:

type: integer

example: 400

message:

type: string

example: " 参数缺失：用户名不能为空 "

'401':

description: 身份验证失败

content:

application/json:

schema:

type: object

properties:

code:

type: integer

example: 401

message:

type: string

example: " 用户名或密码错误 "

'500':

description: 服务器内部错误

content:

application/json:

schema:

type: object

properties:

code:

type: integer

example: 500

message:

type: string

example: " 服务器内部错误： xxx"

components:

securitySchemes:

bearerAuth:

type: http

scheme: bearer

bearerFormat: JWT

security:

- bearerAuth: []

代码注释符合 PEP8 规范（含功能、参数、备注），API 文档支持 Swagger 导入（结构完整、包含参数/ 响应/ 错误码），可直接复制到项目中使用，方便同事调用和维护。

本文节选自《千问高效办公的方法和技巧》，获出版社和作者授权发布。

ITPub博客

代码注释、API文档生成（使用千问AI助手）

最新文章