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

Question

I am used to adding annotations on my REST controllers for Swagger-UI to use. However, I would prefer to point Swagger-UI at a YAML file which describes my REST controller. An example of what I want to do is shown below. (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

Note that I am trying to tell Swagger to build a Docket based on a YAML file rather than a REST controller.

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

This is a sample YAML file describing what my REST controller looks like, and this is what I want Swagger-UI to use.

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

If this is not possible with a YAML file but it is possible using some other format (like JSON), feel free to answer with that solution instead.

Answer 1

You need to inject your YAML definition via SwaggerResourceProvider .

If you need to preserve annotation-based swagger:

@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;
        };
    }
}

if you want to use just swagger based on 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;
        };
    }
}

you need to put your YAML file to src/main/resource/static