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


85

我有一个用简单的Spring编写的ReSTFul API(没有Spring Boot,没有花哨的东西!)。我需要在其中实现Swagger。到目前为止,互联网上的每个页面都以令人困惑的配置和肿的代码(使我根本无法移植)而使我发疯。

有没有人有一个示例项目(或一组详细的步骤)可以帮助我实现这一目标?特别是,我正在寻找使用swagger-springmvc的良好示例。我知道它有“样本”,但充其量,深奥的代码令人不快。

我必须澄清,我不是在寻找“为什么Swagger就是最好的”。我没有使用(或当前的任务将不使用)Spring Boot等。


4
通过示例,我假设您是指github.com/adrianbk/swagger-springmvc-demo。实际上,我鼓励您直接在swagger-springmvc上打开一张票,因为对他们而言,重要的是要知道一些潜在用户可能觉得文档不足,因此他们可以对此进行改进。
罗恩

Answers:


122

Springfox(Swagger spec 2.0,当前)

Springfox取代了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类:

@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使用杰克逊进行数据绑定。

现在添加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(以前为:)显示UI 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/");
    }

}

新的静态文档生成功能看起来也很不错,尽管我自己还没有尝试过。

Swagger-SpringMVC(Swagger spec 1.2,旧版本)

Swagger-SpringMVC的文档可能会有些混乱,但实际上设置起来非常简单。最简单的配置需要创建一个SpringSwaggerConfigbean并启用基于注释的配置(您可能已经在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();
    }

}

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

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

然后index.html在Swagger UIdist目录的顶层编辑文件。在文件顶部,您将看到一些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实例。


1
@MikhailBatcer:我已经用Springfox的Maven依赖关系更新了答案。这是您需要包括在项目中的唯一依赖项,除非您还需要Swagger UI或静态文档。
woemler

2
看起来UI网址现在是/myapp/swagger-ui.html,而不是/ springfox
chrismarx 2015年

7
为了完整起见:springfox“ SwaggerConfig”示例中的“ regex”方法来自“ springfox.documentation.builders.PathSelectors.regex(String)”。如果花了我一段时间才弄清楚;)
cheneym

2
我采取了增加自由的PathSelectors.regex
态度,

1
值得注意的是:如果完全按照这些说明进行操作,并且未使用SpringBoot,则由于从Maven检索的springfox和springfox-ui库的版本不同,您将收到运行时错误。相反,请尽可能使用两者的最新版本(2.5.0如我所写的那样)
Kip

13

添加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/"/>

或春季注释 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-resources时我仍然得到404 swagger-ui.html。有小费吗?可能会有更多的资源映射?
蒂姆·布斯(TimBüthe)2016年

似乎招摇动摇的资源不在根上下文中。可以通过将DispatcherServlet映射到根上下文来解决。请查看问题修复问题983Q。如何为非springboot应用程序配置swagger-ui?
Yuriy Tumakha '16

By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.