如何在应用程序 url /swagger 显示静态 swagger yaml 文件答案

【问题标题】：How to display static swagger yaml file at application url /swagger如何在应用程序 url /swagger 显示静态 swagger yaml 文件
【发布时间】：2019-10-18 21:16:42
【问题描述】：

我创建了 yaml 文件（openapi 3.0.0 格式）作为我们 API 的文档。我想在应用程序运行的 URL 上显示这个（静态）swagger-ui yaml 文件。类似 http://localhost:8080/swagger-ui 的东西。在哪里显示 yaml 文件的图形表示（与 here 相同）。 Yaml文件放在项目的根文件夹中。

我在 java 11、springboot 2.1.5 上运行应用程序，使用 maven 构建。

我尝试使用

从代码中生成 swagger yaml

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

但这并不完美（缺少默认值、描述..）

我尝试了spring static resources，但没有成功。问题是yaml文件不是html。

还有其他（可能更好）的方式，如何显示 api 文档？

【问题讨论】：

标签： java spring-boot swagger-ui

【解决方案1】：

我们能够使用@Configugarion 类完成这项任务

@Configuration
    public class SwaggerConfiguration implements WebMvcConfigurer {

      private final String swaggerUILocation = "whatEverLocationYouWant";
      private final String swaggerApiDocsLocation = "whatEverLocationYouWant";

      @Override
      public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler(swaggerUILocation + "**")
            .addResourceLocations("classpath:/swagger-ui/");
        registry.addResourceHandler(swaggerApiDocsLocation + "**")
            .addResourceLocations("classpath:/swagger/");
      }
    }

然后我们使用swagger-ui jar文件，解压到resources文件夹中，在这里替换index.html文件中的一行：

<script>
      window.onload = function () {
        // Begin Swagger UI call region
        const ui = SwaggerUIBundle({
          url: "placeHereExactLinkToYourYamlFile",
          dom_id: '#swagger-ui',
          deepLinking: true,
          presets: [
            SwaggerUIBundle.presets.apis,
            SwaggerUIStandalonePreset
          ],
          plugins: [
            SwaggerUIBundle.plugins.DownloadUrl
          ],
          layout: "StandaloneLayout"
        })
        // End Swagger UI call region

        window.ui = ui
      }
    </script>

swagger html 是可见的，并且在应用程序旁边工作。

【讨论】：

【解决方案2】：

您还需要添加 swagger UI 依赖项。

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

然后您可以使用 swagger ui 访问，

http://localhost:9090/swagger-ui.html#/

尝试将此添加到您的方法中，

public void yourMethod(@ApiParam(name = "id", required = true, value = "The id of the site", defaultValue = "3F7B07E2") String id)

【讨论】：

我已经写过了，抱歉，我不写了。但是生成文档的问题是缺少默认值和描述（必须手动完成，否则我错了？）。所以我已经创建了这个 yaml 文件，但我不知道如何在应用程序旁边的 html 中显示它。
我已经编辑了我的答案。尝试在您的方法中添加 @ApiParam 注释
感谢您提供的信息，但我们使用的是从 xsd 文件生成的对象。而那些生成的文件根本无法编辑。我将在回答中描述我们的解决方案。