Swagger ..无法呈现此定义提供的定义未指定有效的版本字段

Question

无法呈现此定义。提供的定义未指定有效的版本字段。

请指出有效的Swagger或OpenAPI版本字段。支持的版本字段是大写字母：“ 2.0”以及与openapi相匹配的字段：3.0.n（例如，openapi：3.0.0）。

我需要在哪里插入正确的版本来停止以下错误。Swagger编辑器工作正常，但是在启动特定项目时收到此错误。非常感谢

Answer 1

我今天遇到了同样的问题。在我的情况下，它是Gson导致错误的配置。如果您也使用Gsonwith SpringMVC，也许您可​​以试试这个：

我正在使用 spring boot 2.2.4 和 spring fox swagger 2.9.2 设置一个 rest-api 项目。由于我Gson比更熟悉Jackson，我替换了默认的 MessageConverter：

@Configuration
@EnableWebMvc
public class MvcConfiguration implements WebMvcConfigurer {

    private final Gson gson = new Gson();

    // ......

    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        GsonHttpMessageConverter gsonHttpMessageConverter = new GsonHttpMessageConverter();
        gsonHttpMessageConverter.setGson(gson);
        converters.add(gsonHttpMessageConverter);
    }

    // ......

}

之后，“ http://localhost:8080/swagger-ui.html ”像描述的问题一样中断。然后我在浏览器中输入“ http://localhost:8080/v2/api-docs ”并注意到swagger doc被包装到另一层，有一个不必要的“值”字段，如下所示：

{
    value: "{"swagger":"2.0","info":{"description": ......}}"
}

毫无疑问，"swagger":"2.0"如果 api-docs 产生类似的东西，swagger 就找不到这个领域。“value”字段的值是实际的swagger doc。

经过一番搜索后，我发现如果不这样做，Gson 会错误地对 swagger 文档进行序列化。解决方案很简单 - 为您的 Gson bean 注册一个用于 swagger 的序列化程序：

{
    value: "{"swagger":"2.0","info":{"description": ......}}"
}

其中Json是通过提供springfox一类：

import springfox.documentation.spring.web.json.Json;

希望这会有所帮助。

Answer 2

在这种情况下，您的API定义缺少OpenAPI / Swagger版本号"swagger": "2.0"。在开始时添加它，如下所示：

{
    "swagger": "2.0",

    "title" : "Music API Documentation",
    ...

Answer 3

我现在在 .net core 项目中遇到过这个问题两次。

在Configure方法中Startup.cs，我需要验证为 UI 呈现的 json 的路径。那应该看起来像：

app.UseSwaggerUI(c => { c.SwaggerEndpoint("./v1/swagger.json", "MyServiceAPI"); });

Answer 4

如果您的 API 定义（浏览到您的 api-docs 端点）是 JSON 并且其中已转义双引号，则此解决方案可以帮助您。

问题是端点返回一个包含 JSON 的字符串。Spring 现在尝试找到一个将 String 转换为 JSON 的消息转换器，因为请求映射定义了produces = MediaType.APPLICATION_JSON_VALUE. 这将是（在我的例子中）Jackson 消息转换器（MappingJackson2HttpMessageConverter具体来说），它将字符串转换为 JSON。

要解决此问题，您必须StringHttpMessageConverter 在MappingJackson2HttpMessageConverter.

StringHttpMessageConverter messageConverter = new StringHttpMessageConverter();
messageConverter.setSupportedMediaTypes(List.of(MediaType.APPLICATION_JSON, MediaType.TEXT_PLAIN, MediaType.ALL));
converters.add(messageConverter);

请注意，它MediaType.APPLICATION_JSON已添加到转换器支持的 MediaType 列表中。

现在 Spring 将按顺序循环遍历转换器并找到 String 消息转换器作为合适的转换器。