在 Spring MVC 应用程序中实现 Swagger 的“简单”方法

Posted 2023-02-16

【中文标题】在 Spring MVC 应用程序中实现 Swagger 的“简单”方法

【英文标题】：A 'simple' way to implement Swagger in a Spring MVC application

【发布时间】：2014-12-30 10:54:27

【问题描述】：

我有一个用简单的 Spring 编写的 ReSTFul API（没有 Spring Boot，没有花哨的东西！）。我需要在其中实现 Swagger。到目前为止，互联网上的每一个页面都只是让我发疯，因为配置混乱，代码臃肿，我发现根本无法移植。

有没有人有一个示例项目（或一组详细的步骤）可以帮助我完成这项工作？特别是，我正在寻找一个使用 swagger-springmvc 的好示例。我知道它有“样本”，但充其量是深奥的代码令人沮丧。

我必须澄清，我不是在寻找“为什么 Swagger 是最好的”。我没有使用（对于我当前的任务也不会使用）Spring Boot 之类的。

【问题讨论】：

通过示例，我假设您指的是github.com/adrianbk/swagger-springmvc-demo。我实际上鼓励您直接在 swagger-springmvc 上开票，因为让他们知道他们的一些潜在用户可能会觉得文档不足，以便他们可以改进它，这一点很重要。

这个有帮助***.com/questions/26807791/…

使用最新的 Spec V3 - 这对于最小配置很有用***.com/a/64333853/410439

【参考方案1】：

Springfox（Swagger 规范 2.0，当前）

Springfox 已取代 Swagger-SpringMVC，现在支持 Swagger 规范 1.2 和 2.0。实现类已更改，允许进行更深入的自定义，但需要进行一些工作。 documentation 已改进，但仍需要添加一些细节以进行高级配置。 1.2 实现的旧答案仍然可以在下面找到。

Maven 依赖项

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
</dependency> 

最低限度的实现看起来或多或少相同，但现在使用 Docket 类而不是 SwaggerSpringMvcPlugin 类：

@Configuration
@EnableSwagger2
public class SwaggerConfig 

    @Bean
    public Docket api()
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.regex("/api/.*"))
            .build()
            .apiInfo(apiInfo());
    

    private ApiInfo apiInfo() 
        return new ApiInfoBuilder()
            .title("TITLE")
            .description("DESCRIPTION")
            .version("VERSION")
            .termsOfServiceUrl("http://terms-of-services.url")
            .license("LICENSE")
            .licenseUrl("http://url-to-license.com")
            .build();
    

您的 Swagger 2.0 API 文档现在可以通过 http://myapp/v2/api-docs 获得。

注意：如果你没有使用 Spring boot，那么你应该添加 jackson-databind 依赖。由于springfox使用jackson进行数据绑定。

现在添加 Swagger UI 支持变得更加容易。如果您使用的是 Maven，请为 Swagger UI webjar 添加以下依赖项：

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

如果您使用的是 Spring Boot，那么您的 Web 应用程序应自动获取必要的文件并在 http://myapp/swagger-ui.html（以前为：http://myapp/springfox）处显示 UI。如果您不使用 Spring Boot，那么正如 yuriy-tumakha 在下面的答案中提到的那样，您将需要为文件注册一个资源处理程序。 Java 配置如下所示：

@Configuration
@EnableWebMvc
public class WebAppConfig extends WebMvcConfigurerAdapter 

    @Override 
    public void addResourceHandlers(ResourceHandlerRegistry registry) 
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    

static documentation generation 的新功能看起来也很不错，虽然我自己还没有尝试过。

Swagger-SpringMVC（Swagger 规范 1.2，更早版本）

Swagger-SpringMVC 的文档可能有点混乱，但实际上设置起来非常容易。最简单的配置需要创建一个 SpringSwaggerConfig bean 并启用基于注释的配置（您可能已经在 Spring MVC 项目中这样做了）：

<mvc:annotation-driven/>
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />

但是，我认为使用 SwaggerSpringMvcPlugin 而不是以前的 XML 定义的 bean 定义自定义 Swagger 配置的额外步骤是值得的：

@Configuration
@EnableSwagger
@EnableWebMvc
public class SwaggerConfig 

    private SpringSwaggerConfig springSwaggerConfig;

    @SuppressWarnings("SpringJavaAutowiringInspection")
    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) 
        this.springSwaggerConfig = springSwaggerConfig;
    

    @Bean
    public SwaggerSpringMvcPlugin customImplementation()

        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                .apiInfo(apiInfo())
                .includePatterns(".*api.*"); // assuming the API lives at something like http://myapp/api
    

    private ApiInfo apiInfo() 
        return new ApiInfoBuilder()
            .title("TITLE")
            .description("DESCRIPTION")
            .version("VERSION")
            .termsOfServiceUrl("http://terms-of-services.url")
            .license("LICENSE")
            .licenseUrl("http://url-to-license.com")
            .build();
    

当您运行应用程序时，您现在应该会看到在 http://myapp/api-docs 创建的 API 规范。要设置精美的 Swagger UI，您需要从 GitHub project 克隆静态文件并将它们放入您的项目中。确保您的项目配置为提供静态 HTML 文件：

<mvc:resources mapping="*.html" location="/" />

然后在 Swagger UI dist 目录的顶层编辑 index.html 文件。在文件的顶部，您会看到一些 javascript 引用了另一个项目的 api-docs URL。编辑它以指向您项目的 Swagger 文档：

  if (url && url.length > 1) 
    url = url[1];
   else 
    url = "http://myapp/api-docs";
  

现在，当您导航到 http://myapp/path/to/swagger/index.html 时，您应该会看到项目的 Swagger UI 实例。

【讨论】：

@MikhailBatcer：我已经使用 Springfox 的 Maven 依赖项更新了答案。这是您需要在项目中包含的唯一依赖项，除非您还需要 Swagger UI 或静态文档。

看起来 UI url 现在是 /myapp/swagger-ui.html 而不是 /springfox

为了完整性：springfox 'SwaggerConfig' 示例中的 'regex' 方法来自 'springfox.documentation.builders.PathSelectors.regex(String)'。如果我花了很长时间才弄清楚；）

我冒昧地添加了PathSelectors. 来帮助那些在静态导入regex 时遇到困难的人

值得注意：如果完全遵循这些说明，并且不使用 SpringBoot，由于从马文。相反，如果可能的话，从两者的最新版本开始（2.5.0 我写这篇文章）

【参考方案2】：

在添加 WebJar 依赖项和资源映射后，Springfox Swagger UI 对我有用。 http://www.webjars.org/documentation#springmvc

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.2.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.2.2</version>
    </dependency>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>bootstrap</artifactId>
        <version>3.3.5</version>
    </dependency>

spring-servlet.xml：

<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

或 Spring 注解 https://github.com/springfox/springfox-demos/blob/master/spring-java-swagger/src/main/java/springfoxdemo/java/swagger/SpringConfig.java

应该启用 Swagger2

 @EnableSwagger2
 public class SwaggerConfiguration 
 

【讨论】：

这对我帮助很大，但是在打开 swagger-ui.html 时，我仍然在 /swagger-resources 上收到 404。有小费吗？更多资源映射可能吗？

看起来 swagger-resources 不在根上下文中。它可以通过将 DispatcherServlet 映射到根上下文来修复。查看问题修复 issue 983 和 Q. How does one configure swagger-ui for non-springboot applications?

【参考方案3】：

你也可以考虑使用swagger-maven-plugin生成swagger.json，复制到你的static swagger-ui中。

请在此 repo 上检查带有 Spring MVC 注释的工作插件的简单示例：

https://github.com/khipis/swagger-maven-example

或用于 JAX-RS

https://github.com/kongchen/swagger-maven-example