SpringBoot+Swagger2+Asciidoctor输出静态文档

1. 软件依赖

Spring Boot

Swagger2

Swagger2markup

asciidoctor-maven-plugin

2. SpringBoot配置Swagger2

2.1 引入Swagger2相关依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>
        <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>

2.1 编写SwaggerConfig配置类

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.xxx.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .description("API使用说明")
                .termsOfServiceUrl("http://localhost:8088")
                .version("1.0")
                .build();
    }
}

@SpringBootApplication
@EnableSwagger2
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication .class, args);
    }
}

2.2 在controller的方法上添加swagger注解

    @ApiOperation(value = "删除指定ID标记")
    @ApiImplicitParam(name = "id", value = "标记ID", required = true, dataType = "string")
    @RequestMapping(value = "/mark/{id}", method = RequestMethod.DELETE)
    public void delete(@PathVariable String id) {
        markService.delete(id);
    }
    
    @ApiOperation(value = "查询指定ID标记")
    @ApiImplicitParam(name = "id", value = "标记ID", required = true, dataType = "string")
    @RequestMapping(value = "/mark/{id}", method = RequestMethod.GET)
    public TblMark getById(@PathVariable String id) {
        return markService.getById(id);
    }
    
    @ApiOperation(value = "更新指定ID标记")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "标记ID", required = true, dataType = "string"),
        @ApiImplicitParam(name = "mark", value = "标记实体TblMark", required = true, dataType = "TblMark")
    })
    @RequestMapping(value = "/mark/{id}", method = RequestMethod.PUT)
    public TblMark update(@PathVariable String id,@RequestBody TblMark mark) {
        return markService.update(id, mark);
    }

3. 编写测试类生成asciidoc

    @Test
    public void generateAsciiDocs() throws MalformedURLException {
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder().withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .build();
        Swagger2MarkupConverter.from(new URL("http://localhost:8088/v2/api-docs")).withConfig(config).build()
                .toFile(Paths.get("src/docs/asciidoc/generated/all"));
    }

3. 使用asciidoctor-maven-plugin生成HTML文档

3.1 配置asciidoctor-maven-plugin插件

3.1.1 添加插件仓库

    <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>

3.1.2 配置插件的sourceDirectory属性为asciidoc文档地址

                <plugin>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctor-maven-plugin</artifactId>
                    <version>${asciidoctor.maven.plugin.version}</version>
                    <dependencies>
                        <!-- 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>
                    <configuration>
                        <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                        <attributes>
                            <endpoint-url>http://example.org</endpoint-url>
                            <sourcedir>${project.build.sourceDirectory}</sourcedir>
                            <project-version>${project.version}</project-version>
                        </attributes>
                    </configuration>
                    <executions>
                        <execution>
                            <id>asciidoc-to-html</id>
                            <phase>generate-resources</phase>
                            <goals>
                                <goal>process-asciidoc</goal>
                            </goals>
                            <configuration>
                                <backend>html5</backend>
                                <sourceHighlighter>coderay</sourceHighlighter>
                                <attributes>
                                    <imagesdir>./images</imagesdir>
                                    <toc>left</toc>
                                    <icons>font</icons>
                                    <sectanchors>true</sectanchors>
                                    <idprefix />
                                    <idseparator>-</idseparator>
                                    <docinfo1>true</docinfo1>
                                </attributes>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>

4. 生成文档

4.1 运行asciidoc测试类

4.2 运行mvn generate-resources，在target/generated-docs下生成html文档

5.注意

5.1 POM文件中的<pluginManagement>标签会让其中的插件不执行，导致错误

5.2 <execution>标签的错误可在eclipse中选择quickFix，进行忽略