Question

我习惯在REST控制器上添加注释，以供Swagger-UI使用。但是，我希望将Swagger-UI指向描述我的REST控制器的YAML文件。下面显示了我想做的一个例子。（Springfox / Swagger2）

DemoApplication.java

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");
    }
}

SwaggerConfig.java

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

swagger: "2.0"

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

swagger.yml

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

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'
}

build.gradle

insertBefore()

如果使用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的招摇工具

：

@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

如何使Swagger-UI使用YAML / JSON而不是在REST控制器上放置注释？

1 个答案: