使用swagger2markup生成API文档

一、引入依赖

1. 新版

<dependency>
    <groupId>io.github.swagger2markupgroupId>
    <artifactId>swagger2markupartifactId>
    <version>1.3.2version>
dependency>

2. 旧版

 <dependency>
    <groupId>io.github.robwingroupId>
    <artifactId>swagger2markupartifactId>
    <version>0.9.2version>
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.asciidoctorgroupId>
    <artifactId>asciidoctor-maven-pluginartifactId>
    <version>1.5.6version>
    <configuration>
        <sourceDirectory>${project.basedir}/src/docssourceDirectory>
        <sourceDocumentName>index.adocsourceDocumentName>
        <attributes>
            <doctype>bookdoctype>
            <toc>lefttoc>
            <toclevels>3toclevels>
            <numbered>numbered>
            <hardbreaks>hardbreaks>
            <sectlinks>sectlinks>
            <sectanchors>sectanchors>
            <generated>${project.basedir}/src/docsgenerated>
        attributes>
    configuration>
    <executions>
        <execution>
            <id>output-htmlid>
            <phase>testphase>
            <goals>
                <goal>process-asciidocgoal>
            goals>
            <configuration>
                <backend>html5backend>
                <outputDirectory>${project.basedir}/src/docs2outputDirectory>
            configuration>
        execution>
    executions>
plugin>

四、执行命令mvn clean package

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

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

<plugin>
    <groupId>com.github.kongchengroupId>
    <artifactId>swagger-maven-pluginartifactId>
    <version>3.1.1version>
    <configuration>
        <apiSources>
            <apiSource>
                <springmvc>falsespringmvc>
                <locations>com.hiekn.demo.restlocations>
                <schemes>http,httpsschemes>
                <host>192.168.1.119:8080host>
                <basePath>/apibasePath>
                <info>
                    <title>PlantRobot CMS APItitle>
                    <version>v1version>
                    <description>

                    description>
                    <termsOfService>
                        http://blog.csdn.net/dh798417147
                    termsOfService>
                    <contact>
                        <email>[email protected]email>
                        <name>dinghaoname>
                        <url>http://blog.csdn.net/dh798417147url>
                    contact>
                    <license>
                        <url>http://www.apache.org/licenses/LICENSE-2.0.htmlurl>
                        <name>Apache 2.0name>
                    license>
                info>
                <securityDefinitions>
                securityDefinitions>
                <swaggerDirectory>${basedir}/jsonswaggerDirectory>
            apiSource>
        apiSources>
    configuration>
    <executions>
        <execution>
            <phase>compilephase>
            <goals>
                <goal>generategoal>
            goals>
        execution>
    executions>

    <dependencies>
        <dependency>
            <groupId>io.swaggergroupId>
            <artifactId>swagger-hibernate-validationsartifactId>
            <version>1.5.6version>
        dependency>
    dependencies>
plugin>

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

  
    org.asciidoctor
    asciidoctorj
    1.5.6


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());