Spring Boot中使用Swagger2构建强大的RESTful API文档

 http://blog.didispace.com/swagger2markup-asciidoc/

添加插件

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

                io.github.swagger2markup
                swagger2markup-maven-plugin
                1.3.1
                
                    http://localhost:8080/v2/api-docs
                    
                    src/docs/asciidoc/generated/all
                    
                        ASCIIDOC
                        
                    
                
            
            
                org.asciidoctor
                asciidoctor-maven-plugin
                1.5.6
                
                    src/docs/asciidoc/generated
                    src/docs/asciidoc/html
                    html
                    coderay
                    
                        left
                    
                
            

先启动应用程序，确保http://localhost:8080/v2/api-docs 可以正常访问

执行mvn命令

mvn swagger2markup:convertSwagger2markup

生产adoc文件后再生产HTML

mvn asciidoctor:process-asciidoc

查看文件

swagger2常用注解说明

一个不错的swagger ui

        
        
            com.github.xiaoymin
            swagger-bootstrap-ui
            1.8.2
        

修复 swaggerfox 升级 2.9.2 java.lang.NumberFormatException

 生产环境中禁用

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${swagger.show}")
    private boolean swaggerShow;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerShow)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hexin.messagecenter.controller.api"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("message-center APIs")
                .description("消息中心接口")
//                .termsOfServiceUrl("http://www.hxlc.com/")
                .version("1.0")
                .build();
    }
}

配置中添加

swagger:
  show: false

Spring Cloud Gateway整合Swagger聚合微服务系统API文档(非Zuul)