1. 准备Debian系统环境
在Debian系统上生成Swagger API文档前，需确保系统已更新并安装基础工具：
sudo apt update && sudo apt upgrade -y
根据后续选择的工具（Node.js/Java/Python），安装对应依赖（如Node.js、Java JDK、Python等）。
2. 常见工具链及生成步骤
Swagger文档生成可通过代码注解（适用于Java/Spring Boot）或配置文件+工具（适用于Node.js/Python）实现，以下是具体方案：
适用于基于Node.js的Debian应用，通过代码注释和配置文件自动生成文档。
swagger-jsdoc（解析注释生成文档）和swagger-ui-express（集成Swagger UI）：sudo npm install -g swagger-jsdoc swagger-ui-express
swagger.yaml（或swagger.json），定义API基本信息、端点、参数及模型（示例见下文）。const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./path/to/swagger.yaml');
const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
app.listen(3000, () => console.log('Server running on port 3000'));
swagger.yaml）：swagger: '2.0'
info:
title: Sample API
description: A demo API for Swagger documentation
version: 1.0.0
host: localhost:3000
basePath: /api
paths:
/users:
get:
summary: List all users
responses:
'200':
description: An array of users
schema:
type: array
items:
$ref: '#/definitions/User'
definitions:
User:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
http://localhost:3000/api-docs即可查看交互式文档。适用于Java生态的Debian应用，支持自动生成客户端代码和文档。
方式1：Swagger Codegen（命令行生成）
wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.29/swagger-codegen-cli-3.0.29.jar -O swagger-codegen-cli.jar
swagger-codegen命令生成HTML格式文档（需提前编写swagger.yaml）：java -jar swagger-codegen-cli.jar generate -i path/to/swagger.yaml -l html2 -o path/to/output
openapi-generator-maven-plugin）在构建时自动生成文档（示例见下文）。方式2：SpringFox（代码注解生成）
pom.xml中添加SpringFox依赖：<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
.paths(PathSelectors.any())
.build();
}
}
http://localhost:8080/swagger-ui.html查看文档。适用于Python生态的Debian应用（如Flask/Django），通过装饰器或配置生成文档。
Flask + Flasgger
python3 -m venv swagger-env
source swagger-env/bin/activate
pip install flasgger
from flask import Flask, jsonify
from flasgger import Swagger
app = Flask(__name__)
swagger = Swagger(app)
@app.route('/api/v1/hello')
def hello():
"""This is a sample endpoint.
---
responses:
200:
description: A greeting message
schema:
type: object
properties:
message:
type: string
"""
return jsonify(message="Hello, World!")
http://localhost:5000/apidocs查看文档。Django + DRF-YASG
pip install drf-yasg
settings.py中添加drf_yasg到INSTALLED_APPS，并创建URL路由：from django.urls import path
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
schema_view = get_schema_view(
openapi.Info(title="Sample API", default_version='v1'),
public=True,
permission_classes=[]
)
urlpatterns = [
path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
]
http://localhost:8000/swagger/查看文档。3. 注意事项
