使用swagger2markup生成API文档

一、引入依赖

1. 新版

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

2. 旧版

 <dependency>
    <groupId>io.github.robwin</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>0.9.2</version>
</dependency>

二、读取swagger.json生成ASCIIDOC或者MARKDOWN

1. 新版

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withPathsGroupedBy(GroupBy.TAGS)
        .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withOutputLanguage(Language.ZH)
        .build();
try {
    Swagger2MarkupConverter.from(new URL("http://192.168.1.9:8888/api/swagger.json"))
            .withConfig(config)
            .build()
            .toFolder(Paths.get("src/docs"));
} catch (MalformedURLException e) {
    e.printStackTrace();
}

2. 旧版

Swagger2MarkupConverter.from("json" + "/swagger.json")
        .withPathsGroupedBy(GroupBy.TAGS)/
        .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .build()
        .intoFolder("doc");

三、利用maven插件asciidoctor-maven-plugin生成HTML5或PDF

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.6</version>
    <configuration>
        <sourceDirectory>${project.basedir}/src/docs</sourceDirectory>
        <sourceDocumentName>index.adoc</sourceDocumentName>
        <attributes>
            <doctype>book</doctype>
            <toc>left</toc>
            <toclevels>3</toclevels>
            <numbered></numbered>
            <hardbreaks></hardbreaks>
            <sectlinks></sectlinks>
            <sectanchors></sectanchors>
            <generated>${project.basedir}/src/docs</generated>
        </attributes>
    </configuration>
    <executions>
        <execution>
            <id>output-html</id>
            <phase>test</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>html5</backend>
                <outputDirectory>${project.basedir}/src/docs2</outputDirectory>
            </configuration>
        </execution>
    </executions>
</plugin>

四、执行命令mvn clean package

五、第三步亦可以用maven插件替代、第四步中亦可以用java代码替代生成

1. 如下是替代第三步做法

<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>3.1.1</version>
    <configuration>
        <apiSources>
            <apiSource>
                <springmvc>false</springmvc>
                <locations>com.hiekn.demo.rest</locations>
                <schemes>http,https</schemes>
                <host>192.168.1.119:8080</host>
                <basePath>/api</basePath>
                <info>
                    <title>PlantRobot CMS API</title>
                    <version>v1</version>
                    <description>

                    </description>
                    <termsOfService>
                        http://blog.csdn.net/dh798417147
                    </termsOfService>
                    <contact>
                        <email>[email protected]</email>
                        <name>dinghao</name>
                        <url>http://blog.csdn.net/dh798417147</url>
                    </contact>
                    <license>
                        <url>http://www.apache.org/licenses/LICENSE-2.0.html</url>
                        <name>Apache 2.0</name>
                    </license>
                </info>
                <securityDefinitions>
                </securityDefinitions>
                <swaggerDirectory>${basedir}/json</swaggerDirectory>
            </apiSource>
        </apiSources>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>

    <dependencies>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-hibernate-validations</artifactId>
            <version>1.5.6</version>
        </dependency>
    </dependencies>
</plugin>

2. 如下是替代第四步做法

  <dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj</artifactId>
    <version>1.5.6</version>
</dependency>

Asciidoctor asciidoctor = Asciidoctor.Factory.create();
Attributes attributes = new Attributes();
attributes.setCopyCss(true);
attributes.setLinkCss(false);
attributes.setSectNumLevels(3);
attributes.setAnchors(true);
attributes.setSectionNumbers(true);
attributes.setHardbreaks(true);
attributes.setTableOfContents(Placement.LEFT);
attributes.setAttribute("generated", "F:\\IDEAProject\\meta-boot\\src\\docs");
OptionsBuilder optionsBuilder = OptionsBuilder.options()
        .backend("html5")
        .docType("book")
        .eruby("")
        .inPlace(true)
        .safe(SafeMode.UNSAFE)
        .attributes(attributes);
String asciiInputFile = "src/docs/index.adoc";
asciidoctor.convertFile(
        new File(asciiInputFile),
        optionsBuilder.get());