提供的定义在渲染 openapi 时未指定有效的版本字段

Question

我正在将 OpenAPI 与我的项目集成，当我访问 url:

http://127.0.0.1:11014/swagger-ui/index.html

时，显示如下错误：

Unable to render this definition
The provided definition does not specify a valid version field.

Please indicate a valid Swagger or OpenAPI version field. Supported version fields are swagger: "2.0" and those that match openapi: 3.0.n (for example, openapi: 3.0.0).

 

这是 OpenAPI 配置：

package misc.config.openapi;

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * https://springdoc.org/
 * https://github.com/springdoc/springdoc-openapi
 */
@Configuration
public class OpenApiConfig {

    @Bean
    public GroupedOpenApi fortuneApi() {
        GroupedOpenApi.Builder builder = GroupedOpenApi.builder()
                .pathsToMatch("/fortune/**")
                .group("dddd");
        GroupedOpenApi groupedOpenApi = builder.build();
        return groupedOpenApi;
    }

    @Bean
    public OpenAPI fortuneAPI() {
        return new OpenAPI()
                .info(new Info().title("Fortune API")
                        .description("Spring shop sample application")
                        .version("v0.0.1")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("SpringShop Wiki Documentation")
                        .url("https://springshop.wiki.github.org/docs"));
    }

}

我已阅读问题Swagger..无法呈现此定义提供的定义未指定有效的版本字段并尝试了答案，两者均无效。我应该怎么做才能指定版本？这是依赖关系：

    api "org.springdoc:springdoc-openapi-ui:1.6.9"

我做了一个最小的重现，发现正常响应是json对象，但问题响应返回字符串。这是正确的回答：

{
    "openapi": "3.0.1",
    "info": {
        "title": "Fortune API",
        "description": "Spring shop sample application",
        "license": {
            "name": "Apache 2.0",
            "url": "http://springdoc.org"
        },
        "version": "v0.0.1"
    },
    "externalDocs": {
        "description": "SpringShop Wiki Documentation",
        "url": "https://springshop.wiki.github.org/docs"
    },
    "servers": [
        {
            "url": "http://127.0.0.1:11018",
            "description": "Generated server url"
        }
    ],
    "paths": {},
    "components": {}
}

这是我项目中的问题响应：

"{\"openapi\":\"3.0.1\",\"info\":{\"title\":\"Fortune API\",\"description\":\"Spri......

Answer 1

最后我发现我改变了json转换器导致了这个问题，这是一个解决方法：

@EnableWebMvc
@Configuration
public class WebConvertConfig implements WebMvcConfigurer {

    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        MappingJackson2HttpMessageConverter jackson2HttpMessageConverter = new MappingJackson2HttpMessageConverter();
        converters.add(new StringHttpMessageConverter());
    }
}

这个

StringHttpMessageConverter

应该是第一个添加到转换器中的。我认为这是openapi的设计问题导致其难以使用。更多信息请点击这里：

• https://github.com/springdoc/springdoc-openapi/issues/624
• 端点“/api-docs”不适用于自定义 GsonHttpMessageConverter
• https://github.com/springdoc/springdoc-openapi/issues/683
• https://github.com/swagger-api/swagger-core/issues/1826
• https://github.com/springdoc/springdoc-openapi/issues/900

Answer 2

我遇到了同样的事情，但原因不同。端点

v3/api-docs

返回一个base64字符串而不是json。 （类似于：

eyJvcGVuYXBpIjoiMy4wLjEiLCJpbmZvIjp7InRpdGxlIjoiT3BlbkFQSSBkZWZpbml0aW9uIiwid..

）。

经过一番搜索，我发现当覆盖默认的 spring-boot 注册时

HttpMessageConverter

，您还应该注册 ByteArrayHttpMessageConverter 以获得适当的 springdoc-openapi 支持。

        converters.add(new ByteArrayHttpMessageConverter());
        converters.add(new MappingJackson2HttpMessageConverter(jacksonBuilder.build()));

注意：注册 HttpMessageConverters 时，顺序非常重要。

参考资料：

• https://springdoc.org/#why-am-i-getting-an-error-swagger-ui-unable-to-render-definition-when-overriding-the-default-spring-registered-httpmessageconverter
• https://github.com/springdoc/springdoc-openapi/issues/2143