Swagger2 在Springboot>2.0+Spring >4.3中的配置

1.maven配置dependency

        
            com.github.xiaoymin
            swagger-bootstrap-ui
            1.6
            compile
        
        
            io.springfox
            springfox-swagger2
            2.8.0
            compile
        
        
            net.minidev
            json-smart
            2.3
        
        
            org.json
            json
            20180130
        

        

2.配置文件

@Configuration
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfiguration {


    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wondersgroup.healthcloud.api"))
                .paths(PathSelectors.any())
                .build();
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("neohealthcloud-sichuan-server-user-api")
                .description("neohealthcloud-sichuan-server-user-api")
                .termsOfServiceUrl("localhost:8080")
                .license("Apache license")
                .contact("[email protected]")
                .version("1.0")
                .build();
    }
}

3.为了防止在生产环境恶意攻击api接口，建议关闭生产环境通过swagger api对接口的访问

public class SwaggerCondition implements Condition {

    @Override
    public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
        return !"re".equals(context.getEnvironment().getProperty("spring.profiles.active"));
    }
}

4.为了使Swagger2在启是生成有效资源增加配置

@Configuration
@EnableWebMvc
public class WebConfig extends WebMvcConfigurerAdapter {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        //        Swagger2 配置
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }
}

5.高级用法
参考：https://segmentfault.com/a/1190000010911014

5.1Maven插件生成API描述文档（json格式）

 com.github.kongchen
 swagger-maven-plugin
 3.1.5
 
     
         
             true
             com.example.demo13
             orderdish-ecom-web.51ping.com
             /s
             http,https
             
                 
                 v1
                 Click Link Below for Help
                 http://www.github.com/kongchen/swagger-maven-plugin
             
             
             
             
             
             ${project.build.directory}/swagger-ui
             yaml,json
         
     
 
 
     
         compile
         
             generate
         
     
 

执行mvn complie，在设置的target目录下会生成API描述文档。

5.2Maven插件生成API描述文档（markdown格式）

 io.github.swagger2markup
 swagger2markup-maven-plugin
 1.3.3
 
     
     ${project.build.directory}/swagger-ui/swagger.yaml
     ${project.build.directory}/swagger-ui
     ${project.build.directory}/swagger-ui/swagger.md
     
         
         MARKDOWN
         
         TAGS
     
 
 
     
         compile
         
             convertSwagger2markup
         
     
 

执行mvn complie，在设置的target目录下会生成API描述文档。
如果mvn complie时出现异常，可能是因为之前生成的yaml不符合Swagger规范。把yaml复制到Swagger Editor中，根据提示的语法错误修正，再手动执行mvn swagger2markup:convertSwagger2markup即可生成markdown文档。

感谢：
https://segmentfault.com/a/1190000010911014
https://blog.csdn.net/biren_wang/article/details/78947558