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

Question

有没有人有一个样例项目（或者一组详细的步骤）可以帮助我完成这件事？特别是，我正在寻找一个使用swagger-springMVC的好样例。我知道它有“示例”，但最多，深奥的代码是令人气馁的。

我必须澄清，我不是在寻找“为什么大摇大摆的简直就是最好的”。我没有使用（并且对于我当前的任务将不会使用）Spring引导或这样的。

Answer 1

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

}

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

@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的文档可能有点混乱，但实际上它非常容易设置。最简单的配置需要创建springswagerconfigbean并启用基于注释的配置（您可能已经在Spring MVC项目中这样做了）：

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

但是，我认为非常值得采取额外的步骤，使用swaggerspringMVCPlugin来定义一个自定义的Swagger配置，而不是前面的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();
    }

}

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

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

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