Swagger2 在 SpringMVC 项目中的应用

最新推荐文章于 2025-08-20 17:55:57 发布

weixin_34319374

最新推荐文章于 2025-08-20 17:55:57 发布

阅读量99

点赞数

CC 4.0 BY-SA版权

文章标签： java json python

原文链接：https://my.oschina.net/bbsyuemoncn/blog/953400

本文详细介绍如何在Spring MVC项目中集成Springfox Swagger2，包括添加Maven依赖、配置SwaggerConfig类以及展示Swagger UI的方法。此外，还解决了项目启动过程中可能出现的异常问题。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

2019独角兽企业重金招聘Python工程师标准>>>

添加 Maven 依赖

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

<dependency>
	<groupId>com.fasterxml.jackson.core</groupId>
	<artifactId>jackson-annotations</artifactId>
	<version>2.7.4</version>
</dependency>
<dependency>
	<groupId>com.fasterxml.jackson.core</groupId>
	<artifactId>jackson-databind</artifactId>
	<version>2.7.4</version>
</dependency>
<dependency>
	<groupId>com.fasterxml.jackson.core</groupId>
	<artifactId>jackson-core</artifactId>
	<version>2.7.4</version>
</dependency>

其中 springfox-swagger2 用于在访问 http://myapp/v2/api-docs 时生成API的 json 数据, springfox-swagger-ui则用于将 json 数据以 HTML 的形式将API展示出来,便于在线调试.

v2/api-docs 这个路径定义在 springfox-swagger2 项目中的 Swagger2Controller 类中, 每次访问 http://myapp/v2/api-docs 都将生成一个 Swagger 对象,并使用 jackson 的 ObjectMapper 对象将 Swagger 对象转成 json 返回给浏览器,因此这里也要添加 jackson 的相关依赖.

springfox 的相关仓库地址如下

Release

<repositories>
    <repository>
      <id>jcenter-Release</id>
      <name>jcenter</name>
      <url>https://jcenter.bintray.com/</url>
    </repository>
</repositories>

Snapshots

<repositories>
    <repository>
      <id>jcenter-snapshots</id>
      <name>jcenter</name>
      <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
    </repository>
</repositories>

添加 SwaggerConfig 配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import com.ckjava.test.web.ApiController;

import io.swagger.annotations.Api;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableWebMvc
@EnableSwagger2
/* @ComponentScan(basePackageClasses = { ApiController.class }) */
@ComponentScan(basePackages = "com.ckjava.test.web")
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
            .paths(PathSelectors.any())
            .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();
    }

}

其中 @ComponentScan(basePackages = "com.ckjava.test.web") 指出 @Controller 类所在的包名.
也可以通过 @ComponentScan(basePackageClasses = { ApiController.class }) 指出具体的 @Controller 类
其中 RequestHandlerSelectors.withClassAnnotation(Api.class) 指出只扫描带有 io.swagger.annotations.Api 注解的类
WebAppConfig 配置类用于配置展示 Swagger 的 UI, 具体如下

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

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

}

等项目启动后可以通过 http://myapp/swagger-ui.html 访问到开放的API

可能遇到的问题

项目启动中遇到 java.lang.NoClassDefFoundError: com/fasterxml/classmate/members/ResolvedParameterizedMember 异常

原因如下: 由于在 springfox-swagger2 中依赖了 classmate-1.3.1.jar 而项目中使用了 hibernate-validator 其中又依赖了 classmate-1.0.0.jar,需要在 hibernate-validator 排除 classmate 依赖

解决如下:

<dependency>
	<groupId>org.hibernate</groupId>
	<artifactId>hibernate-validator</artifactId>
	<version>${validator.version}</version>
	<exclusions>
		<exclusion>
			<groupId>com.fasterxml</groupId>
			<artifactId>classmate</artifactId>
		</exclusion>
	</exclusions>
</dependency>