[Swagger] Asciidoc 配置静态章节
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
更多
扫码关注或搜索架构探险之道获取最新文章，不积跬步无以至千里，坚持每周一更，坚持技术分享^_^ ！