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的文档可能会有些混乱,但实际上设置起来非常简单。最简单的配置需要创建一个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.*");
}
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实例。