Swagger2与Spring REST Docs

编者注

以前让其余写服务端的小伙伴支持swagger，而后最近一直在写Unity，没有把以前的项目和Swagger进行集成

Swagger Core

Swagger Core Git

Swagger 2.X 快速开始

注意：Swagger 2.x 遵循OpenApi 3.0定义的文件。若是你指望使用1.5.x版本的Swagger或者OpenApi 2.0，请参考1.5.X JAX-RS Setup

SpringBoot与Swagger2

Gradle

dependencies {
	// 原生UI
	//compile("io.springfox:springfox-swagger-ui:2.9.2")
	// 国内人编写的左右分隔的UI
	compile("com.github.xiaoymin:swagger-bootstrap-ui:1.8.9")
    compile("io.springfox:springfox-swagger2:2.9.2")
	//...
}

配置

因为springboot须要手动编写配置Bean，则代码以下

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .groupName("groupName")
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.aicfve"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo getApiInfo(){
        return new ApiInfoBuilder()
                .title("swagger-bootstrap-ui RESTful APIs")
                .description("Descrption")
                .termsOfServiceUrl("http://localhost")
                .contact("zhanpeng@bfa.edu.cn")
                .version("1.0")
                .build();
    }
}

运行后，经过http://localhost:8080/doc.html可以看到swagger-bootstrap-ui内容，可是看不到Controller内容。其余内容须要添加描述

Api注解

访问URL

springfox-swagger-ui

http://localhost:8080/swagger-ui.html

swagger-bootstrap-ui

http://localhost:8080/doc.html

路由配置

有些地方须要添加springmvc的路由，则以下代码，注意WebMvcCOnfigurerAdpator已经放弃

@Configuration
public class SwaggerMvcConfigurer implements WebMvcConfigurer {
    private static final Logger logger = LoggerFactory.getLogger(SwaggerMvcConfigurer.class);

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        logger.info("Add Resource Handlers");
//        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
//
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

特别注意

springcloud-config-server 没法与Swagger集成，springcloud-config会屏蔽路由 https://github.com/spring-cloud/spring-cloud-config/issues/759

Spring REST Docs - 翻译

https://spring.io/projects/spring-restdocs

Overview

Spring REST Docs为RESTful文档进行服务。
经过Asciidoctor绑定手写文档，而且自动生成[Spring MVC Test]的片断。经过这种方法，把你从Swagger文档工具中解放出来。
帮助你准确、简洁、结构化的构建文档。文档仅需用户不多的信息。

Spring Boot Config

Spring Boot在测试中提供 @AutoConfigureRestDocs注解用于Spring REST Docs的连接。

快速开始

经过Spring Initializr 启动应用。