如何让 Swagger-UI 使用 YAML/JSON 而不必在我的 REST 控制器上添加注释? [英] How do I make Swagger-UI use a YAML/JSON rather than having to put annotations on my REST controller?

问题描述

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

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

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

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

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

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

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

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.

推荐答案

你需要通过 SwaggerResourceProvider 注入你的 YAML 定义.

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

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

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

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

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

这篇关于如何让 Swagger-UI 使用 YAML/JSON 而不必在我的 REST 控制器上添加注释?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！