Swagger离线文档生成方式

Swagger离线文档

程序引入swagger资源

• swagger配置教程： springboot项目引入swagger2

• 工程引入swagger生成对应html，通过ip+/v2/api-docs获取相应json

具体实现

• pom文件引入资源

<properties>
	<!--swagger导出参数-->
	<swagger2markup.version>1.2.0</swagger2markup.version> 
	<asciidoctor.input.directory>${project.basedir}/src/docs/asciidoc</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>
	<swagger.input>${project.basedir}/src/docs/asciidoc/swagger.json</swagger.input>
</properties>

<!--为生成swagger离线文档包-->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-staticdocs</artifactId>
	<version>2.6.1</version>
</dependency>
<dependency>
	<groupId>io.github.swagger2markup</groupId>
	<artifactId>swagger2markup</artifactId>
	<version>1.3.1</version>
</dependency>

<build>
  <plugins>
      <plugin>
          <groupId>io.github.swagger2markup</groupId>
          <artifactId>swagger2markup-maven-plugin</artifactId>
          <version>${swagger2markup.version}</version>
          <dependencies>
              <dependency>
                  <groupId>io.github.swagger2markup</groupId>
                  <artifactId>swagger2markup-import-files-ext</artifactId>
                  <version>${swagger2markup.version}</version>
              </dependency>
              <dependency>
                  <groupId>io.github.swagger2markup</groupId>
                  <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
                  <version>${swagger2markup.version}</version>
              </dependency>
          </dependencies>
          <configuration>
              <swaggerInput>${swagger.input}</swaggerInput>
              <outputDir>${generated.asciidoc.directory}</outputDir>
              <config>
                  <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                  <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
                  <swagger2markup.extensions.dynamicOverview.contentPath>${project.basedir}/src/docs/asciidoc/extensions/overview</swagger2markup.extensions.dynamicOverview.contentPath>
                  <swagger2markup.extensions.dynamicDefinitions.contentPath>${project.basedir}/src/docs/asciidoc/extensions/definitions</swagger2markup.extensions.dynamicDefinitions.contentPath>
                  <swagger2markup.extensions.dynamicPaths.contentPath>${project.basedir}/src/docs/asciidoc/extensions/paths</swagger2markup.extensions.dynamicPaths.contentPath>
                  <swagger2markup.extensions.dynamicSecurity.contentPath>${project.basedir}src/docs/asciidoc/extensions/security/</swagger2markup.extensions.dynamicSecurity.contentPath>
              </config>
          </configuration>
          <executions>
              <execution>
                  <phase>test</phase>
                  <goals>
                      <goal>convertSwagger2markup</goal>
                  </goals>
              </execution>
          </executions>
      </plugin>
      <plugin>
          <groupId>org.asciidoctor</groupId>
          <artifactId>asciidoctor-maven-plugin</artifactId>
          <version>1.5.3</version>
          <dependencies>
              <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}</generated>
              </attributes>
          </configuration>
          <executions>
              <execution>
                  <id>output-html</id>
                  <phase>test</phase>
                  <goals>
                      <goal>process-asciidoc</goal>
                  </goals>
                  <configuration>
                      <backend>html5</backend>
                      <outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
                  </configuration>
              </execution>
          </executions>
      </plugin>
  </plugins>
</build>

• Java实现

 /**
  * Copyright (C), 2018-2020
  * FileName: Swagger2MarkupCreate
  * Author:   Lee
  * Date:     2020/3/26 11:27
  * Description:通过该类生成asciidoc-generated下.adoc文件，之后通过mvn test生成html文档
  * History:
  */
 package com.yc.swagger.config;
 
 import io.github.swagger2markup.GroupBy;
 import io.github.swagger2markup.Language;
 import io.github.swagger2markup.Swagger2MarkupConfig;
 import io.github.swagger2markup.Swagger2MarkupConverter;
 import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
 import io.github.swagger2markup.markup.builder.MarkupLanguage;
 
 import java.nio.file.Path;
 import java.nio.file.Paths;
 
 /**
  * @author Lee
  * @create 2020/3/26
  * @since 1.0.0
  */
 public class Swagger2MarkupCreate {
 
     //指定adoc文件生成路径
     public Path outputDirectory = Paths.get("inner-intergration/swagger-core/target/asciidoc/generated");
 
     //通过配置文件生成swagger2markup的参数
     public Swagger2MarkupConfig config;
 
     public Swagger2MarkupCreate(String Json){
          /*输出Ascii格式     
          config = new Swagger2MarkupConfigBuilder()
                 .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                 .withOutputLanguage(Language.ZH).withPathsGroupedBy(GroupBy.TAGS)
                 .withGeneratedExamples().withoutInlineSchema().build();
           */ 
         /*输出Markdown格式
         config = new Swagger2MarkupConfigBuilder()
                 .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                 .withOutputLanguage(Language.ZH).withPathsGroupedBy(GroupBy.TAGS)
                 .withGeneratedExamples().withoutInlineSchema().build();
         */        
         // 输出Confluence使用的格式
         config = new Swagger2MarkupConfigBuilder()
                 .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
                 .withOutputLanguage(Language.ZH).withPathsGroupedBy(GroupBy.TAGS)
                 .withGeneratedExamples().withoutInlineSchema().build();
         //获取本地json数据
         createAdocFile(Paths.get(Json));
     }
     /**
      * 通过json文件生成adoc文件
      */
     public void createAdocFile(Path localSwaggerFile){
         Swagger2MarkupConverter.from(localSwaggerFile)
                 .withConfig(config)
                 .build()
                 .toFolder(outputDirectory);
     }
     public static void main(String[] args){
         //指定本地json文件路径
         new Swagger2MarkupCreate("inner-intergration/swagger-core/src/docs/asciidoc/swagger.json");
 
     }
 }

• 创建index.adoc放置在项目src/docs/asciidoc下

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

• 操作流程
  • 将获取的swagger.json放置在src/docs/asciidoc下
  • 运行Swagger2MarkupCreate类，生成index.adoc文件下的4个adoc文件
  • 执行mvn test命令生成index.html离线文档页面（在target/asciidoc/html下）
  • 该html页面即为离线生成接口文档

相关文件材料

• swagger.json
  该文件为项目swagger文件，将项目启动后通过ip+doc.html访问swagger主页面，在主页面点击localhost:8080/v2/api-docs获取
  

官方API