SpringBoot+Swagger，生成.adoc/.md/html/pdf格式API文档

卡卡木樨

已于 2022-07-18 15:16:07 修改

阅读量1.4k

点赞数

分类专栏：工具使用文章标签： spring boot html

于 2022-07-18 15:14:13 首次发布

本文链接：https://blog.csdn.net/she8292802/article/details/125845812

版权

工具使用专栏收录该内容

8 篇文章 0 订阅

订阅专栏

1 选择Swagger版本

2 配置Swagger

3 启动项目

4 生成 .adoc 和 .md 格式文档

1 选择Swagger版本

pom.xml

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.5.0</version>
    </parent>

    <groupId>com.demo</groupId>
    <artifactId>com-test-api</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <name>com-test-api Maven Webapp</name>
    <!-- FIXME change it to the project's website -->
    <url>http://www.example.com</url>

    <properties>

    </properties>

    <dependencies>
       

        <!-- swagger导出所需依赖 -->
        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.9.0.RELEASE</version>
        </dependency>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.3</version>
        </dependency>

       

    </dependencies>

    <build>
        <finalName>com-test-api-${project.version}</finalName>
        <plugins><!-- lock down plugins versions to avoid using Maven defaults (may be moved to parent pom) -->

       

            <!--swagger静态化插件 先执行测试类生成.adoc文件再运行maven命令 asciidoctor:process-asciidoc生成html-->
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <configuration>
                    <sourceDirectory>./docs/asciidoc/generated</sourceDirectory>
                    <outputDirectory>./docs/asciidoc/html</outputDirectory>
                    <headerFooter>true</headerFooter>
                    <doctype>book</doctype>
                    <backend>html</backend>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <!--菜单栏在左边-->
                        <toc>left</toc>
                        <!--多标题排列-->
                        <toclevels>3</toclevels>
                        <!--自动打数字序号-->
                        <sectnums>true</sectnums>
                    </attributes>
                </configuration>
            </plugin>

            <plugin>
                <artifactId>maven-clean-plugin</artifactId>
                <version>3.1.0</version>
            </plugin>
            <!-- see http://maven.apache.org/ref/current/maven-core/default-bindings.html#Plugin_bindings_for_war_packaging -->
            <plugin>
                <artifactId>maven-resources-plugin</artifactId>
                <version>3.0.2</version>
            </plugin>
            <plugin>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.0</version>
            </plugin>
            <plugin>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>2.22.1</version>
            </plugin>
            <plugin>
                <artifactId>maven-war-plugin</artifactId>
                <version>3.2.2</version>
            </plugin>
            <plugin>
                <artifactId>maven-install-plugin</artifactId>
                <version>2.5.2</version>
            </plugin>
            <plugin>
                <artifactId>maven-deploy-plugin</artifactId>
                <version>2.8.2</version>
            </plugin>
        </plugins>
    </build>
</project>

2 配置Swagger

Swagger2Config.java

package com.test.config.swagger;

import com.yixin.netc.bic.im.constant.ConstantSystem;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;


@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.demo.com.test.api.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(getPars())
                .apiInfo(apiInfo());
    }


    private List<Parameter> getPars(){

        ParameterBuilder pBuiler1 = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();

        pBuiler1.name(ConstantSystem.HEADER_AUTH).description("Bearer token")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false).build();
   
        pars.add(pBuiler1.build());
        return pars;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .description("文档描述")
                .version("V1.0.0")
                .build();
    }

}

3 启动项目

启动项目，确保Swagger API正常访问；http://localhost:9012/api/swagger-ui.html#/

4 生成 .adoc 和 .md 格式文档

新建测试类：Swagger2ConfigTest.java

执行方法generateAsciiDocs()，会在目录：/docs/asciidoc/generated生成.adoc格式文档

执行方法generateMarkdownDocs()，会在目录：/docs/markdown/generated生成.md格式文档

package com.test.config.swagger;

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 org.junit.Test;

import java.net.MalformedURLException;
import java.net.URL;
import java.nio.file.Paths;

//@ActiveProfiles("win-debug")
public class Swagger2ConfigTest{

    /**
     * 项目运行后，运行此方法
     */
    @Test
    public void generateAsciiDocs() {
        //step1：输出Ascii格式
        try {
            //    输出Ascii格式   asciidoctor:process-asciidoc
            Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                    .withMarkupLanguage(MarkupLanguage.ASCIIDOC)//设置生成格式
                    .withOutputLanguage(Language.ZH)//设置语言中文还是其他语言
                    .withPathsGroupedBy(GroupBy.TAGS)
                    .withGeneratedExamples()
                    .withoutInlineSchema()
                    .build();
            //设置swagger-api的json来源
            Swagger2MarkupConverter.from(new URL("http://localhost:9012/api/v2/api-docs"))
                    .withConfig(config)
                    .build()
                    .toFolder(Paths.get("./docs/asciidoc/generated"));//设置生成文件的路径
        } catch (MalformedURLException e) {
            e.printStackTrace();
        }
    }

    @Test
    public void generateMarkdownDocs() {
        //step1：输出Ascii格式
        try {
            //    输出Ascii格式   asciidoctor:process-asciidoc
            Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                    .withMarkupLanguage(MarkupLanguage.MARKDOWN)//设置生成格式
                    .withOutputLanguage(Language.ZH)//设置语言中文还是其他语言
                    .withPathsGroupedBy(GroupBy.TAGS)
                    .withGeneratedExamples()
                    .withoutInlineSchema()
                    .build();
            //设置swagger-api的json来源
            Swagger2MarkupConverter.from(new URL("http://localhost:9012/api/v2/api-docs"))
                    .withConfig(config)
                    .build()
                    .toFolder(Paths.get("./docs/markdown/generated"));//设置生成文件的路径
        } catch (MalformedURLException e) {
            e.printStackTrace();
        }
    }

    @Test
    public void generateHtml() {
        // 通过插件生成html文件(根据ASCIIDOC生成html)
        // asciidoctor:process-asciidoc
    }

}