目錄

• 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

asciidoc-syntax-quick-reference

---

更多

掃碼關注“架構探險之道”，獲取更多源碼和文章資源

知識星球(掃碼加入獲取源碼和文章資源鏈接)

總結

以上是生活随笔為你收集整理的[Swagger] Asciidoc 配置静态章节的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。