编者注

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

Swagger Core

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 启动应用。

来源：oschina

链接：https://my.oschina.net/u/52678/blog/3012963

标签

springfox

swagger

Spring REST Docs

Swagger UI