如何让 Swagger-UI 使用 YAML/JSON 而不必在我的 REST 控制器上添加注释？

Question

我习惯于在我的 REST 控制器上添加注释以供 Swagger-UI 使用。但是，我更愿意将 Swagger-UI 指向描述我的 REST 控制器的 YAML 文件。我想要做的一个例子如下所示。 (Springfox/Swagger2)

DemoApplication.java

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

SwaggerConfig.java

请注意，我试图告诉 Swagger 基于 YAML 文件而不是 REST 控制器构建 Docket。

import com.google.common.base.Predicate;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import static springfox.documentation.builders.PathSelectors.regex;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2).useDefaultResponseMessages(false)
                .select()
                .paths(paths())
                .build();
    }

    private Predicate<String> paths() {
        return regex("/swagger.yml");
    }
}

swagger.yml

这是一个示例 YAML 文件，描述了我的 REST 控制器的外观，这是我希望 Swagger-UI 使用的。

swagger: "2.0"

paths:
  /animals:
      post:
        summary: Creates an animal.
        responses:
          '201':
            description: Created.

build.gradle

plugins {
    id 'org.springframework.boot' version '2.1.3.RELEASE'
    id 'java'
}

apply plugin: 'io.spring.dependency-management'

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '1.8'

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'

    implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.8.0'
    implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.8.0'
}

如果 YAML 文件无法做到这一点，但可以使用其他格式（如 JSON），请随意使用该解决方案来回答。

Answer 1

您需要通过SwaggerResourceProvider 注入您的 YAML 定义。

如果需要保留基于注解的招摇：

@Configuration
@EnableSwagger2
public class SwaggerConfig {


    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    @Primary
    @Bean
    public SwaggerResourcesProvider swaggerResourcesProvider(InMemorySwaggerResourcesProvider defaultResourcesProvider) {
        return () -> {
            SwaggerResource wsResource = new SwaggerResource();
            wsResource.setName("Documentation");
            wsResource.setSwaggerVersion("2.0");
            wsResource.setLocation("/swagger.yaml");

            List<SwaggerResource> resources = new ArrayList<>(defaultResourcesProvider.get());
            resources.add(wsResource);
            return resources;
        };
    }
}

如果你只想使用基于 YAML 的 swagger：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Primary
    @Bean
    public SwaggerResourcesProvider swaggerResourcesProvider() {
        return () -> {
            SwaggerResource wsResource = new SwaggerResource();
            wsResource.setName("Documentation");
            wsResource.setSwaggerVersion("2.0");
            wsResource.setLocation("/swagger.yaml");

            List<SwaggerResource> resources = List.of(wsResource);
            return resources;
        };
    }
}

你需要把你的 YAML 文件放到src/main/resource/static