swagger導出離線文檔

參考：

https://blog.csdn.net/ii19910410/article/details/90031310

https://www.cnblogs.com/james-roger/p/13183661.html

https://www.cnblogs.com/jpfss/p/11438606.html

https://www.cnblogs.com/hanxue112253/p/10983483.html

https://blog.csdn.net/u012888052/article/details/115208796

swagger的HTML文檔已經很完美了，但總有一些時候，需要靜態的文件文檔。這時候就需要配置一些插件。

一、swagger相關的依賴pom

   <!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.5.0</version>
        </dependency>

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

        <!--  swagger導出PDF/HTML所需依賴  -->
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>

二、maven插件

在maven-build-plugins下面增加兩個插件

 <plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.2.0</version>
                <configuration>
                    <!--此處端口一定要是當前項目啟動所用的端口-->
                    <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
                    <!--生成多個文件-->
<!--                    <outputDir>src/docs/asciidoc/generated</outputDir>-->
                    <!--生成單個文件-->
                    <outputFile>src/docs/asciidoc/api</outputFile>
                    <config>
                        <!-- 除了ASCIIDOC之外，還有MARKDOWN和CONFLUENCE_MARKUP可選，下面生成HTML和PDF的的插件依賴ASCIIDOC格式 -->
                        <swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>
                    </config>
                </configuration>
            </plugin>

            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.3</version>
                <!-- Include Asciidoctor PDF for pdf generation -->
                <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>
                <!-- Configure generic document generation settings -->
                <configuration>
<!--                    對應上面插件的outputdir-->
<!--                    <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>-->
<!--                    對應上面插件的outputfile-->
                    <sourceDirectory>src/docs/asciidoc</sourceDirectory>
                    <sourceDocumentName>api.adoc</sourceDocumentName>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <toc>left</toc>
                    </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>src/docs/asciidoc/html</outputDirectory>
                        </configuration>
                    </execution>
<!--                    pdf中文有亂碼，目前不太好用-->
                    <execution>
                        <id>output-pdf</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
                        </configuration>
                    </execution>

                </executions>
            </plugin>

三、swagger配置文件（可選）

有時候發現swagger生成的接口文檔里有一些springboot自己的接口，這些是調試用的，對外根本不需要，怎么可以從文檔里把這些去掉呢，就需要swagger配置類指定我需要的接口的所在包，這樣其他的接口就不會出現了。

@EnableSwagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("cc.group.articid.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

 

四、maven命令

 1.mvn swagger2markup:convertSwagger2markup

2.mvn generate-resources

第一個插件生成adoc文件，也可以選擇生成md文件

第二個插件需要依賴第一個插件的adoc文件，PDF中文會有亂碼，我是用上一步的md文件導出的PDF，也很方便

還有如果喜歡HTML的文件，第二個插件會生成一個HTML文件，也很方便。