debian swagger如何生成文档

在 Debian 上“用 Swagger 生成文档”通常有两种常见场景，我分别说明，你按需选择即可。

一、Java 项目（Spring Boot + Swagger / SpringDoc）

1. 使用 Swagger 2（旧）

依赖（Maven）

<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"))
                .paths(PathSelectors.any())
                .build();
    }
}

访问

http://localhost:8080/swagger-ui.html

2. 使用 SpringDoc（推荐，Swagger 3）

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.3.0</version>
</dependency>

访问

http://localhost:8080/swagger-ui.html

或

http://localhost:8080/swagger-ui/index.html

二、直接通过 OpenAPI 文件生成静态文档（与语言无关）

1. 安装工具（Debian）

sudo apt update
sudo apt install npm
sudo npm install -g @redocly/cli
# 或
sudo npm install -g swagger-cli

2. 准备 OpenAPI 文件

openapi.yaml

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: OK

3. 生成 HTML 文档

redocly build-docs openapi.yaml -o api.html

或使用 Swagger UI：

npx swagger-cli validate openapi.yaml

三、Debian 上部署 Swagger UI（静态）

git clone https://github.com/swagger-api/swagger-ui.git
cp swagger-ui/dist/* /var/www/html/

把 openapi.json 放到目录中并修改 index.html：

url: "openapi.json"

四、常见命令总结

# 校验
swagger-cli validate openapi.yaml

# 生成文档
redocly build-docs openapi.yaml -o doc.html

如果你能告诉我：

• 用的是 什么语言/框架
• 想生成 网页文档 还是 PDF/HTML
• 是否在 Debian 服务器上部署

我可以给你更精确的方案。