[Swagger] Asciidoc 配置静态章节

目录

• Asciidoc 配置静态章节

• MAVEN
• 静态章节配置
• MAVAN命令切换输出方式
• Asciidoc InteillJ IDEA Plugin
• REFRENCES
• 更多

Asciidoc 配置静态章节

Swagger导出的adoc文档补充静态章节，并通过mvn命令动态判断配置模板

MAVEN

<properties>
    <web-app-name>xxx</web-app-name>
    <_rest>xxx-api-v1</_rest><!--xxx-ui-v1/xxx-api-v1-->
    <_phase>site</_phase>
    <_static>common</_static><!--common/api-->
    <rest.swagger.path>${_rest}</rest.swagger.path>
    <mvn.doc.phase>${_phase}</mvn.doc.phase>
    <adoc.index>asciidoc/${_static}</adoc.index>
    <asciidoctor.input.directory>${project.basedir}/src/docs/${adoc.index}</asciidoctor.input.directory>
    <generated.asciidoc.directory>${project.build.directory}/asciidoc/generated</generated.asciidoc.directory>
    <asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory>
    <asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>
    <swagger.output.zip>${project.build.directory}/xxx-rest-docs</swagger.output.zip>
</properties>

<dependencies>
       <!--springfox-swagger start-->
       <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger2</artifactId>
       </dependency>

       <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger-ui</artifactId>
       </dependency>

       <dependency>
           <groupId>io.swagger</groupId>
           <artifactId>swagger-models</artifactId>
       </dependency>
       <dependency>
           <groupId>io.github.swagger2markup</groupId>
           <artifactId>swagger2markup</artifactId>
       </dependency>
   </dependencies>

<repositories>
       <repository>
           <id>jcentral</id>
           <name>bintray</name>
           <url>http://jcenter.bintray.com</url>
           <snapshots>
               <enabled>false</enabled>
           </snapshots>
       </repository>
       <repository>
           <id>jcenter-snapshots</id>
           <name>jcenter</name>
           <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
       </repository>
   </repositories>

  <build>
    <finalName>${web-app-name}</finalName>
    <plugins>
          <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-surefire-plugin</artifactId>
              <version>2.9</version>
              <configuration>
                <!--此处通过系统参数注入，便于在测试用例中直接获取配置项（接口分组和对应swagger路由）-->
                  <systemPropertyVariables>
                      <io.springfox.staticdocs.outputDir>${project.build.directory}/swagger</io.springfox.staticdocs.outputDir>
                      <io.swagger.json.uris>/v2/api-docs?group=UI,/v2/api-docs?group=API_V1,/v2/api-docs?group=API_INNER_V1,/v2/api-docs?group=API_INNER_V2</io.swagger.json.uris>
                      <io.swagger.json.output.name>xxx-ui-v1.json,xxx-api-v1.json,xxx-inner-v1.json,xxx-inner-v2.json</io.swagger.json.output.name>
                  </systemPropertyVariables>
              </configuration>
          </plugin>
          <!--接口文件生成[adoc -> html & pdf]-->
          <plugin>
              <groupId>org.asciidoctor</groupId>
              <artifactId>asciidoctor-maven-plugin</artifactId>
              <version>1.5.3</version>
              <dependencies>
                  <dependency>
                      <groupId>org.asciidoctor</groupId>
                      <artifactId>asciidoctorj-pdf</artifactId>
                      <version>1.5.0-alpha.10.1</version>
                  </dependency>
                  <dependency>
                      <groupId>org.jruby</groupId>
                      <artifactId>jruby-complete</artifactId>
                      <version>1.7.21</version>
                  </dependency>
              </dependencies>
              <configuration>
                  <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
                  <sourceDocumentName>index.adoc</sourceDocumentName>
                  <attributes>
                      <doctype>book</doctype>
                      <toc>left</toc>
                      <toclevels>3</toclevels>
                      <numbered></numbered>
                      <hardbreaks></hardbreaks>
                      <sectlinks></sectlinks>
                      <sectanchors></sectanchors>
                      <generated>${generated.asciidoc.directory}/${rest.swagger.path}</generated>
                  </attributes>
              </configuration>
              <executions>
                  <execution>
                      <id>output-html</id>
                      <phase>${mvn.doc.phase}</phase>
                      <goals>
                          <goal>process-asciidoc</goal>
                      </goals>
                      <configuration>
                          <sourceHighlighter>coderay</sourceHighlighter>
                          <backend>html5</backend>
                          <attributes>
                              <toc/>
                              <linkcss>false</linkcss>
                          </attributes>
                          <outputDirectory>${asciidoctor.html.output.directory}/${rest.swagger.path}</outputDirectory>
                      </configuration>
                  </execution>
                  <execution>
                      <id>output-pdf</id>
                      <phase>${mvn.doc.phase}</phase>
                      <goals>
                          <goal>process-asciidoc</goal>
                      </goals>
                      <configuration>
                          <backend>pdf</backend>
                          <outputDirectory>${asciidoctor.pdf.output.directory}/${rest.swagger.path}/</outputDirectory>
                      </configuration>
                  </execution>
              </executions>
          </plugin>

          <plugin>
              <groupId>com.coderplus.maven.plugins</groupId>
              <artifactId>copy-rename-maven-plugin</artifactId>
              <version>1.0.1</version>
              <executions>
                  <execution>
                      <id>rename-file-pdf</id>
                      <phase>${mvn.doc.phase}</phase>
                      <goals>
                          <goal>rename</goal>
                      </goals>
                      <configuration>
                          <sourceFile>${asciidoctor.pdf.output.directory}/${rest.swagger.path}/index.pdf</sourceFile>
                          <destinationFile>${swagger.output.zip}/pdf/${rest.swagger.path}.pdf</destinationFile>
                      </configuration>
                  </execution>
                  <execution>
                      <id>rename-file-html</id>
                      <phase>${mvn.doc.phase}</phase>
                      <goals>
                          <goal>rename</goal>
                      </goals>
                      <configuration>
                          <sourceFile>${asciidoctor.html.output.directory}/${rest.swagger.path}/index.html</sourceFile>
                          <destinationFile>${swagger.output.zip}/html/${rest.swagger.path}.html</destinationFile>
                      </configuration>
                  </execution>
                  <execution>
                      <id>rename-file-json</id>
                      <phase>${mvn.doc.phase}</phase>
                      <goals>
                          <goal>rename</goal>
                      </goals>
                      <configuration>
                          <sourceFile>${project.build.directory}/swagger/${rest.swagger.path}.json</sourceFile>
                          <destinationFile>${swagger.output.zip}/json/${rest.swagger.path}.json</destinationFile>
                      </configuration>
                  </execution>
              </executions>
          </plugin>
      </plugins>
  </build>

静态章节配置

xxx-web/src/docs/asciidoc/api/index.adoc

include::{generated}/overview.adoc[]
include::doc_static_strating.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/security.adoc[]
include::doc_static_ending.adoc[]
include::{generated}/definitions.adoc[]

doc_static_strating.adoc和doc_static_ending.adoc参考ASCIIDOC语法进行编辑即可

实际效果

MAVAN命令切换输出方式

• mvn 执行命令生成对应文档

生成对应静态接口文件 & index文件更名并调整目录

• xxx-api-v1
• xxx-inner-v1、xxx-inner-v2
• xxx-ui-v1

配置项说明

-D_phase=test 在mvn test执行期生成静态文档

-D_rest=xxx-api-v1 需要生成静态文档的接口分组

-D_static=common 静态章节在index.adoc的配置

/*默认方式*/
mvn test -D_rest=xxx-api-v1 -D_phase=test -D_static=common
mvn test -D_rest=xxx-ui-v1 -D_phase=test

Asciidoc InteillJ IDEA Plugin

插件安装

编辑效果

REFRENCES

1. asciidoc-syntax-quick-reference

---

更多

扫码关注“架构探险之道”，获取更多源码和文章资源