Swagger自动生成接口文档

Posted 2021-01-25 nodegis

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>w</groupId>
  <artifactId>ww</artifactId>
  <version>1.0-SNAPSHOT</version>

  <name>ww</name>
  <!-- FIXME change it to the project‘s website -->
  <url>http://www.example.com</url>



  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.11</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>io.github.swagger2markup</groupId>
      <artifactId>swagger2markup</artifactId>
      <version>1.3.3</version>
    </dependency>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-nop</artifactId>
      <version>1.7.24</version>
    </dependency>

  </dependencies>
  <repositories>
    <repository>
      <snapshots>
        <enabled>true</enabled>
        <updatePolicy>always</updatePolicy>
      </snapshots>
      <id>jcenter-releases</id>
      <name>jcenter</name>
      <url>http://jcenter.bintray.com</url>
    </repository>
  </repositories>


  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.7</maven.compiler.source>
    <maven.compiler.target>1.7</maven.compiler.target>


    <swagger2markup.plugin.version>1.3.7</swagger2markup.plugin.version>
    <swagger2markup.extension.version>1.3.3</swagger2markup.extension.version>
    <swagger2markup.version>1.3.3</swagger2markup.version>

    <generated.asciidoc.directory>e://doc</generated.asciidoc.directory>
    <swagger.input>http://localhost:7003/gmapi/docs/v1</swagger.input>

    <asciidoctor.input.directory>e://doc</asciidoctor.input.directory>
    <asciidoctor.html.output.directory>e://html</asciidoctor.html.output.directory>

    <jruby.version>9.2.4.1</jruby.version>
    <asciidoctorj.version>v1.6.0-RC.2</asciidoctorj.version>


  </properties>

  <!-- 插件仓储 -->
  <pluginRepositories>
    <pluginRepository>
      <id>jcenter-snapshots</id>
      <name>jcenter</name>
      <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
    </pluginRepository>
    <pluginRepository>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
      <id>jcenter-releases</id>
      <name>jcenter</name>
      <url>http://jcenter.bintray.com</url>
    </pluginRepository>
  </pluginRepositories>

  <build>
    <plugins>
      <!-- First, use the swagger2markup plugin to generate asciidoc -->
      <plugin>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup-maven-plugin</artifactId>
        <version>${swagger2markup.plugin.version}</version>
        <dependencies>
          <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-import-files-ext</artifactId>
            <version>${swagger2markup.extension.version}</version>
          </dependency>
          <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>${swagger2markup.version}</version>
          </dependency>
        </dependencies>
        <configuration>
          <!--The URL or file path to the Swagger specification-->
          <swaggerInput>${swagger.input}</swaggerInput>
          <!-- <outputDir>${generated.asciidoc.directory}</outputDir> -->

          <outputFile>${generated.asciidoc.directory}/swagger</outputFile>
          <config>
            <!--设置输出文件的语言：ASCIIDOC, MARKDOWN, CONFLUENCE_MARKUP-->
            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
            <!-- 方言 -->
            <swagger2markup.outputLanguage>ZH</swagger2markup.outputLanguage>
            <!--设置目录的展现方式-->
            <swagger2markup.pathsGroupedBy>AS_IS</swagger2markup.pathsGroupedBy>
            <!--扩展Overview的内容，可以增加一些自定义的内容-->
            <!--<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>generate-sources</phase>
            <goals>
              <goal>convertSwagger2markup</goal>
            </goals>
          </execution>
        </executions>
      </plugin>



      <!-- Run the generated asciidoc through Asciidoctor to generate
           other documentation types, such as PDFs or HTML5 -->
      <plugin>
        <groupId>org.asciidoctor</groupId>
        <artifactId>asciidoctor-maven-plugin</artifactId>
        <version>1.5.7</version>
        <!-- Include Asciidoctor PDF for pdf generation -->
        <dependencies>
          <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>1.5.0-alpha.16</version>
          </dependency>
          <!-- Comment this section to use the default jruby artifact provided by the plugin -->
          <dependency>
            <groupId>org.jruby</groupId>
            <artifactId>jruby-complete</artifactId>
            <version>${jruby.version}</version>
          </dependency>
          <!-- Comment this section to use the default AsciidoctorJ artifact provided by the plugin -->
          <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj</artifactId>
            <version>${asciidoctorj.version}</version>
          </dependency>
        </dependencies>
        <!-- Configure generic document generation settings -->
        <configuration>
          <!--默认指向 ${basedir}/src/main/asciidoc-->
          <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
          <!--an override to process a single source file; 默认指向 ${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>
        <!-- Since each execution can only handle one backend, run
             separate executions for each desired output type -->
        <executions>
          <execution>
            <id>output-html</id>
            <phase>generate-resources</phase>
            <goals>
              <goal>process-asciidoc</goal>
            </goals>
            <configuration>
              <backend>html5</backend>
              <outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
            </configuration>
          </execution>


          <!-- 生成PDF -->
          <!--<execution>
              <id>output-pdf</id>
              <phase>generate-resources</phase>
              <goals>
                  <goal>process-asciidoc</goal>
              </goals>
              <configuration>
                  <backend>pdf</backend>
                  <outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>
              </configuration>
          </execution>-->

        </executions>
      </plugin>
    </plugins>
    <pluginManagement><!-- lock down plugins versions to avoid using Maven defaults (may be moved to parent pom) -->
      <plugins>
        <plugin>
          <artifactId>maven-clean-plugin</artifactId>
          <version>3.0.0</version>
        </plugin>
        <!-- see http://maven.apache.org/ref/current/maven-core/default-bindings.html#Plugin_bindings_for_jar_packaging -->
        <plugin>
          <artifactId>maven-resources-plugin</artifactId>
          <version>3.0.2</version>
        </plugin>
        <plugin>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>3.7.0</version>
        </plugin>
        <plugin>
          <artifactId>maven-surefire-plugin</artifactId>
          <version>2.20.1</version>
        </plugin>
        <plugin>
          <artifactId>maven-jar-plugin</artifactId>
          <version>3.0.2</version>
        </plugin>
        <plugin>
          <artifactId>maven-install-plugin</artifactId>
          <version>2.5.2</version>
        </plugin>
        <plugin>
          <artifactId>maven-deploy-plugin</artifactId>
          <version>2.8.2</version>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
</project>

　　

mvn install