Swagger2與Spring REST Docs

編者注

以前讓其餘寫服務端的小夥伴支持swagger,而後最近一直在寫Unity,沒有把以前的項目和Swagger進行集成html

Swagger Core

Swagger Core Gitgit

Swagger 2.X 快速開始

注意:Swagger 2.x 遵循OpenApi 3.0定義的文件。若是你指望使用1.5.x版本的Swagger或者OpenApi 2.0,請參考1.5.X JAX-RS Setupgithub

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,則代碼以下web

@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內容。其餘內容須要添加描述spring

Api註解

 

訪問URL

springfox-swagger-uibootstrap

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

swagger-bootstrap-uiapi

http://localhost:8080/doc.html

路由配置

有些地方須要添加springmvc的路由,則以下代碼,注意WebMvcCOnfigurerAdpator已經放棄springboot

@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/759mvc

Spring REST Docs - 翻譯

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

Overview

Spring REST Docs爲RESTful文檔進行服務。
經過Asciidoctor綁定手寫文檔,而且自動生成[Spring MVC Test]的片斷。經過這種方法,把你從Swagger文檔工具中解放出來。
幫助你準確、簡潔、結構化的構建文檔。文檔僅需用戶不多的信息。

Spring Boot Config

Spring Boot在測試中提供 @AutoConfigureRestDocs註解用於Spring REST Docs的連接。

快速開始

經過Spring Initializr 啓動應用。

相關文章
相關標籤/搜索