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

Question

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

请指明有效的 Swagger 或 OpenAPI 版本字段。 支持的版本字段为 swagger: "2.0" 和匹配 openapi: 3.0.n 的字段（例如，openapi: 3.0.0）。

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

Answer 1

您的API 定义缺少 OpenAPI/Swagger 版本号，在本例中为"swagger": "2.0" 。 在开头添加它，如下所示：

{
    "swagger": "2.0",

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

Answer 2

我今天遇到了同样的问题。 就我而言，是Gson配置导致错误。 如果您还将Gson与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": ......}}"
}

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

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

private final Gson gson = new GsonBuilder()
        .registerTypeAdapter(Json.class, new SpringfoxJsonToGsonAdapter())
        .create();

private static class SpringfoxJsonToGsonAdapter implements JsonSerializer<Json> {
    @Override
    public JsonElement serialize(Json json, Type type, JsonSerializationContext context) {
        final JsonParser parser = new JsonParser();
        return parser.parse(json.value());
    }
}

其中Json是 springfox 提供的一个类：

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

希望这会有所帮助。

Answer 3

就我而言，我正在使用

const openapiSpecification = swaggerJsdoc(options);

当我真正需要的时候

const openapiSpecification = await swaggerJsdoc(options);

Answer 4

我现在在一个 .net 核心项目中遇到过这个问题。 （随意告诉我去问我自己的问题）。

在Startup.cs的Configure方法中，我需要验证为 UI 呈现的 json 的路径。 那应该是这样的：

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

至少下次我遇到这个问题时不会如此困惑。

Answer 5

这是 OpenAPI V3 这个问题的解决方案，它对我有用。 我认为这也可能与其他版本相关。

我尝试使用 Gson 而不是 Jackson 作为 Spring 的默认序列化程序。 Gson 生成的 /v3/api-docs 用双引号括起来。 因此 /swagger-ui/index.html 显示了此线程中解决的错误。

回到杰克逊为我解决了这个问题。 如果您必须使用 Gson，也许上面@Lyux 写的解决方案可以适合您。

Answer 6

我也遇到过这个问题，在我的情况下/v3/api-doc被LoginInterceptor拦截，我的解决方案是：

public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {

        if (request.getRequestURI().startsWith("/swagger") || "/v3/api-docs".equals(request.getRequestURI())) {
            return true;
        }

}

Answer 7

遇到过类似的情况，pom上使用的swagger库有；

 <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
     </dependency>
     <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
     </dependency>  

在Application.java指定 Docket Bean

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.scheduling.annotation.EnableAsync;
import org.springframework.scheduling.annotation.EnableScheduling;
import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.context.annotation.Bean;

import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Created by nyakundid
 */
@EnableScheduling
@EnableAsync
@SpringBootApplication
@EnableSwagger2
public class Application implements CommandLineRunner {

    public Log log = LogFactory.getLog(Application.class);


    public static void main(String[] args) {
        SpringApplication.run(Application.class);
    }

    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors.basePackage("com.package.controller")).build();
    }
}

最后在basePackage下创建您的控制器希望它对您有用。

Answer 8

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

问题是端点返回一个包含 JSON 的字符串。 Spring 现在试图找到一个将 String 转换为 JSON 的消息转换器，因为请求映射定义了一个produces = MediaType.APPLICATION_JSON_VALUE 。 这将是（在我的情况下）将字符串转换为 JSON 的 Jackson 消息转换器（ MappingJackson2HttpMessageConverter是MappingJackson2HttpMessageConverter ）。

要解决此问题，您必须在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 消息转换器作为合适的转换器。

Answer 9

这里的一切都对我不起作用，因为我使用的是 yaml 而不是 JSON 我刚刚为解决问题所做的是将 openapi 版本从 openapi: 3.0.0 更改为 openapi: 3.0.1

"

Answer 10

有同样的错误，在我的电脑上本地工作，当 go 到登台服务器给我这个错误时，我使用下面的代码解决了它

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

Answer 11

我正在开发一个没有 UI 组件的 SpringBoot 项目。 假设您已经完成了返回 GroupedOpenApi 和 OpenApi 函数的工作，并且您正在对其进行分类，而不是在 swagger-ui 中显示您的 yaml。

实际问题：返回 yaml 并转义了所有引号。 如此处所示：

"{\"openapi\":\"3.0.1\",\"info\":{\"t

创建一个 WebServlet 以拦截返回的 yaml。 你只需要这个的第一部分：

https://www.javafixing.com/2022/03/fixed-understand-and-configure-spring.html

添加一个端点处理程序来代理响应。 逐字添加（从第一个函数的返回中删除“，null”）：

https://stackoverflow.com/a/70977335/877552

Answer 12

如果您将swagger-express-ui与tsoa 结合使用，并且您的swaggerUi.setup function 未能检测到任何swagger.json文件以从中导入其架构，您可能会看到此错误。 要解决此问题，您可以在本地导入此文件或从 URL 加载它。执行此操作有两种方法：

const options = {
  swaggerOptions: {
    url: 'http://petstore.swagger.io/v2/swagger.json',
   },
};

app.use('/docs', swaggerUi.serve, swaggerUi.setup(undefined, options));
app.use('/api/v1', router);

---

const swaggerDocument = require('../swagger.json');

app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

注意：Eslint 可能会被 require 语句打扰，如果你不想禁用它，你可以使用await代替：

app.use(
 "/docs",
 swaggerUi.serve,
 async (_req: Request, res: Response) =>
 res.send(swaggerUi.generateHTML(await import("../swagger.json"))));

Answer 13

import * as swaggerDocument from './assets/swagger.json'; 

帮助我而不是

import swaggerDocument from './assets/swagger.json';