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

我有一个用简单的 Spring 编写的 ReSTFul API（没有 Spring Boot，没有花哨的东西！）。我需要在其中实现 Swagger。到目前为止，互联网上的每个页面都让我抓狂，因为令人困惑的配置和臃肿的代码我根本找不到可移植性。

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

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

Springfox（Swagger 规范 2.0，当前）

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

Maven 依赖

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

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

@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 应用程序应该自动选取必要的文件并在以下位置显示 UIhttp://myapp/swagger-ui.html（以前：http://myapp/springfox）。如果您不使用 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/");
    }

}

The new 静态文档生成功能看起来也很不错，虽然我自己还没有尝试过。

Swagger-SpringMVC（Swagger 规范 1.2，较旧）

的文档Swagger-SpringMVC可能有点令人困惑，但实际上设置起来非常容易。最简单的配置需要创建一个SpringSwaggerConfigbean 并启用基于注释的配置（您可能已经在 Spring MVC 项目中执行此操作）：

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

然而，我认为采取额外的步骤使用定义自定义 Swagger 配置是非常值得的SwaggerSpringMvcPlugin，而不是之前的 XML 定义的 bean：

@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();
    }

}

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

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

然后编辑index.htmlSwagger UI 顶层的文件dist目录。在文件的顶部，您将看到一些引用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 实例。