在Spring MVC应用程序中实现Swagger的“简单”方法
我有一个简单的Spring写的ReSTFul API（没有Spring Boot，没有花哨的东西！）。 我需要实现Swagger。 到目前为止，互联网上的每一个页面都让我疯狂，因为混乱的configuration和臃肿的代码，我根本找不到可移植的代码。
有没有人有一个示例项目（或一组详细的步骤），可以帮助我做到这一点？ 特别是，我正在寻找一个使用swagger-springmvc的好样本。 我知道它有'样品'，但最好的是，深奥的代码是令人沮丧的。
我必须澄清，我不是在寻找“为什么Swagger是最好的”。 我不使用（而对于我目前的任务不会使用）Spring Boot还是这样的。
Springfox（Swagger spec 2.0，当前版本）
Springfox已经取代了Swagger-SpringMVC，现在支持Swagger 1.2和2.0两个版本。 实现类已经改变，允许一些更深的定制，但有一些工作。 文档已经改进，但仍需要为高级configuration添加一些细节。 1.2的实现的旧答案仍然可以在下面find。
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 。
现在添加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，那么就像在下面的答案中提到的那样，你需要为这些文件注册一个资源处理器。 Javaconfiguration看起来像这样：
@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/"); } }
新的静态文档生成function也看起来不错，虽然我没有尝试过自己。
Swagger-SpringMVC（Swagger spec 1.2，旧）
Swagger-SpringMVC的文档可能有点混乱，但实际上设置起来非常简单。 最简单的configuration需要创build一个SpringSwaggerConfig bean并启用基于注解的configuration（您可能已经在您的Spring MVC项目中做过）：
<mvc:annotation-driven/> <bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
不过，我认为使用SwaggerSpringMvcPlugin而不是以前的XML定义的bean来额外定义Swaggerconfiguration是非常值得的：
@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创build的API规范。 为了使Swagger的UI设置起来，你需要克隆GitHub项目中的静态文件，并把它们放到你的项目中。 确保您的项目configuration为提供静态HTML文件：
<mvc:resources mapping="*.html" location="/" />
然后编辑Swagger UI dist目录顶层的index.html文件。 接近文件顶部，您会看到一些引用另一个项目的api-docs URL的JavaScript。 编辑这个指向你的项目的Swagger文档：
if (url && url.length > 1) { url = url[1]; } else { url = "http://myapp/api-docs"; }
现在，当您导航到http://myapp/path/to/swagger/index.html ，您应该会看到项目的Swagger UI实例。
在添加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 Annotation 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-maven-plugin生成swagger.json并将其复制到你的静态swagger-ui中。
请查看此回购的Spring MVC注释的简单工作插件示例：
https://github.com/khipis/swagger-maven-example
或者JAX-RS
