Swagger UI 导出文档从入门到实战指南

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.OAS_30)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
            .paths(PathSelectors.any())
            .build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("示例 API 文档")
.description("用于演示 Swagger UI 导出文档的示例项目")
.version("1.0.0")
.build();
}
}

curl -o swagger.json http://localhost:8080/v3/api-docs

curl -H "Authorization: Bearer YOUR_TOKEN" \
     -o swagger.json \
     http://localhost:8080/v3/api-docs

jq . swagger.json > /dev/null && echo "JSON 格式合法"

<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.3</version>
</dependency>

import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import java.nio.file.Path;
import java.nio.file.Paths;
public class SwaggerToMarkdown {
public static void main(String[] args) throws Exception {
    Path inputFile = Paths.get("swagger.json");
    Path outputDir = Paths.get("docs");
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.MARKDOWN)
        .withOutputLanguage(Language.ZH)
        .withPathsGroupedBy(GroupBy.TAGS)
        .withGeneratedExamples()
        .build();
Swagger2MarkupConverter converter = Swagger2MarkupConverter
.from(inputFile)
.withConfig(config)
.build();
converter.toFolder(outputDir);
System.out.println("Markdown 文档已生成到: " + outputDir.toAbsolutePath());
}
}

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withOutputLanguage(Language.ZH)
        .build();

npm install -g widdershins

widdershins --language zh \
            --summary \
            --omitHeader \
            --search false \
            swagger.json \
            -o api-docs.md

const widdershins = require('widdershins');
const options = {
language: 'zh',
summary: true,
omitHeader: true,
search: false
};
widdershins.convert('swagger.json', options)
.then(markdown => {
const fs = require('fs');
fs.writeFileSync('api-docs.md', markdown);
console.log('Markdown 文档生成成功');
})
.catch(err => {
console.error('转换失败:', err);
process.exit(1);
});

npm install -g redoc-cli

redoc-cli bundle swagger.json \
    --options.theme.colors.primary.main=#1890ff \
    --title "示例 API 文档" \
    -o api-docs.html

redoc-cli bundle swagger.json \
    --output api-docs.html \
    --options.theme.colors.primary.main=#1890ff
npx --yes puppeteer print-to-pdf api-docs.html api-docs.pdf

npx --yes puppeteer print-to-pdf \
    --landscape \
    --format A4 \
    api-docs.html api-docs.pdf

npm install -g @openapitools/openapi-generator-cli

openapi-generator-cli generate \
    -i swagger.json \
    -g html \
    -o docs/html

openapi-generator-cli generate \
    -i swagger.json \
    -g markdown \
    -o docs/markdown

openapi-generator-cli generate \
    -i swagger.json \
    -g postman-collection \
    -o docs/postman

#!/bin/bash
set -e
API_BASE_URL="${API_BASE_URL:-http://localhost:8080}"
OUTPUT_DIR="${OUTPUT_DIR:-./docs}"
TOKEN="${TOKEN:-}"
echo "开始导出 Swagger 文档..."
mkdir -p "$OUTPUT_DIR"
1. 拉取 OpenAPI 描述文件
echo "拉取 OpenAPI 描述文件..."
if [ -n "$TOKEN" ]; then
curl -H "Authorization: Bearer $TOKEN" 
-o "$OUTPUT_DIR/swagger.json"
"$API_BASE_URL/v3/api-docs"
else
curl -o "$OUTPUT_DIR/swagger.json"
"$API_BASE_URL/v3/api-docs"
fi
2. 使用 widdershins 生成 Markdown
echo "生成 Markdown 文档..."
widdershins --language zh
--summary
--omitHeader
--search false
"$OUTPUT_DIR/swagger.json"
-o "$OUTPUT_DIR/api-docs.md"
3. 使用 redoc-cli 生成 HTML
echo "生成 HTML 文档..."
redoc-cli bundle "$OUTPUT_DIR/swagger.json"
--title "API 文档"
-o "$OUTPUT_DIR/api-docs.html"
4. 使用 Puppeteer 生成 PDF
echo "生成 PDF 文档..."
npx --yes puppeteer print-to-pdf
--landscape
--format A4
"$OUTPUT_DIR/api-docs.html"
"$OUTPUT_DIR/api-docs.pdf"
echo "文档导出完成，输出目录: $OUTPUT_DIR"
ls -lh "$OUTPUT_DIR"

name: Export API Docs
on:
push:
branches: [ main ]
jobs:
export-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm install -g widdershins redoc-cli
- run: chmod +x export-docs.sh
- run: ./export-docs.sh
env:
API_BASE_URL: https://api.example.com
TOKEN: ${{ secrets.API_TOKEN }}
- uses: actions/upload-artifact@v4
with:
name: api-docs
path: docs/

npx --yes puppeteer print-to-pdf \
    --landscape \
    --format A4 \
    --scale 0.8 \
    api-docs.html api-docs.pdf

redoc-cli bundle swagger.json \
    --options.disableSearch \
    -o api-docs.html