swagger生成离线文档

swagger生成离线文档

1. 添加依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
</dependency>

2. 生成swagger.json文件

swagger的配置略过, 网上有很多相同的例子, 随便找一个即可.

@WebAppConfiguration
@RunWith(SpringRunner.class)
@SpringBootTest
@ActiveProfiles("development")
public class SwaggerMarkupUnit {

    private static final String SWAGGER_JSON_HREF = "/v2/api-docs";

    private static final String SWAGGER_JSON_OUT_DIRECTORY = "src/main/resources/documents/swagger.json";

    @Resource
    private WebApplicationContext applicationContext;

    private MockMvc mockMvc;

    @Before
    public void setup() {
        this.mockMvc = MockMvcBuilders.webAppContextSetup(this.applicationContext).build();
    }

    @Test
    public void createSwaggerJson() throws Exception {
        MockHttpServletRequestBuilder requestBuilder = MockMvcRequestBuilders.get(SWAGGER_JSON_HREF)
                .accept(MediaType.APPLICATION_JSON);

        MvcResult mvcResult = this.mockMvc.perform(requestBuilder)
                .andExpect(MockMvcResultMatchers.status().isOk())
                .andReturn();

        MockHttpServletResponse servletResponse = mvcResult.getResponse();
        String swaggerJson = servletResponse.getContentAsString(StandardCharsets.UTF_8);
        Path swaggerPath = Paths.get(SWAGGER_JSON_OUT_DIRECTORY);
        if(Files.notExists(swaggerPath.getParent()) || !Files.isDirectory(swaggerPath.getParent())) {
            Files.createDirectories(swaggerPath.getParent());
        }

        try (BufferedOutputStream outputStream = new BufferedOutputStream(Files.newOutputStream(swaggerPath))){
            StreamUtils.copy(swaggerJson, StandardCharsets.UTF_8, outputStream);
        }
    }

}

运行测试方法, 在document目录下生成swagger.json文件

3. 配置maven插件

<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.7</version>

    <dependencies>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-import-files-ext</artifactId>
            <version>1.3.3</version>
        </dependency>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.3</version>
        </dependency>
    </dependencies>
    <configuration>
        <swaggerInput>src/main/resources/documents/swagger.json</swaggerInput>
        <outputDir>src/main/resources/documents/</outputDir>
        <config>
            <!--设置输出文件的语言：ASCIIDOC, MARKDOWN, CONFLUENCE_MARKUP-->
            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
            <!--设置目录的展现方式-->
            <swagger2markup.pathsGroupedBy>TAGS</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>
<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.14</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>1.7.21</version>
        </dependency>
    </dependencies>
    <configuration>
        <sourceDirectory>src/main/resources/documents</sourceDirectory>
        <!--                    <sourceDocumentName>index.adoc</sourceDocumentName>-->
        <attributes>
            <doctype>book</doctype>
            <toc>left</toc>
            <toclevels>3</toclevels>
            <numbered></numbered>
            <hardbreaks></hardbreaks>
            <sectlinks></sectlinks>
            <sectanchors></sectanchors>
            <generated>src/main/resources/documents/asciidoc</generated>
        </attributes>
    </configuration>
    <executions>
        <execution>
            <id>output-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>html5</backend>
                <outputDirectory>src/main/resources/documents/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>${asciidoctor.pdf.output.directory}</outputDirectory>
                        </configuration>
                    </execution>-->
    </executions>
</plugin>

执行mvn swagger2markup:convertSwagger2markup process-resources