SpringBoot+Swagger2+Asciidoctor输出静态文档

1. 软件依赖

Spring Boot

Swagger2

Swagger2markup

asciidoctor-maven-plugin

2. SpringBoot配置Swagger2

2.1 引入Swagger2相关依赖

        
            io.springfox
            springfox-swagger2
            2.8.0
        
        
            io.springfox
            springfox-swagger-ui
            2.8.0
        
        
            io.springfox
            springfox-staticdocs
            2.6.1
        
        
            io.github.swagger2markup
            swagger2markup
            1.3.1
        

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 添加插件仓库

    
        
            jcenter-snapshots
            jcenter
            http://oss.jfrog.org/artifactory/oss-snapshot-local/
        
        
            
                false
            
            jcenter-releases
            jcenter
            http://jcenter.bintray.com
        
    

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

                
                    org.asciidoctor
                    asciidoctor-maven-plugin
                    ${asciidoctor.maven.plugin.version}
                    
                        
                        
                            org.jruby
                            jruby-complete
                            ${jruby.version}
                        
                        
                        
                            org.asciidoctor
                            asciidoctorj
                            ${asciidoctorj.version}
                        
                    
                    
                        src/docs/asciidoc/generated
                        
                            http://example.org
                            ${project.build.sourceDirectory}
                            ${project.version}
                        
                    
                    
                        
                            asciidoc-to-html
                            generate-resources
                            
                                process-asciidoc
                            
                            
                                html5
                                coderay
                                
                                    ./images
                                    left
                                    font
                                    true
                                    
                                    -
                                    true
                                
                            
                        
                    
                

4. 生成文档

4.1 运行asciidoc测试类

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

5.注意

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

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