【spring-boot①】swagger配置

最新推荐文章于 2025-03-22 00:41:12 发布

冰公主我女神

最新推荐文章于 2025-03-22 00:41:12 发布

阅读量1.1k

点赞数

文章标签： springboot swagger

本文链接：https://blog.youkuaiyun.com/nangu0673/article/details/82587268

版权

本文详述了如何在Spring Boot项目中配置和使用Swagger，包括创建子模块、添加Swagger依赖、配置Swagger类以及编写SwaggerController。通过这些步骤，读者将能成功集成Swagger并使用Swagger-ui进行API文档的展示。

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

写在前边：对于入门者，只需要跟着这篇文章一步步操作，最后一定会成功，成功之后再理解就不难了。有问题可以留言，我会在看到的时候回复。

1. 创建spring boot项目，项目名为zhangxianwen-test，创建方法略

2. 为spring boot项目创建子模块命名为zxw-swagger（注：创建子模块需创建maven项目）

添加完毕之后，父模块也就是zhangxianwen-test中的pom文件中就会自动生成父子模块依赖关系，依赖关键字为子模块的 <artifactId>值。

同样在子模块zxw-swagger的pom文件中也能看到依赖关系

注：将父模块pom文件中的<packaging>jar</packaging>改为<packaging>pom</packaging>，将父模块作为一个pom管理模块。

3. 子模块创建完毕，解释一下创建子模块的原因，因为之后会在父模块下再创建更多的模块进行其他相关技术的学习，所以以模块的方式创建，方便之后的管理，同时也能够对项目的模块化有一定的了解。接下来就是在zxw-swagger模块中完成swagger的配置学习。第一步是在pom中添加swagger依赖，有两种方式：

一种是直接在zxw-swaggerd的pom中添加（必须为其配置版本号，依赖来源为备注的网址），如下：

<dependencies>





<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>2.9.2</version>

</dependency>



<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>2.9.2</version>

</dependency>

</dependencies>

第二种（推荐）就是在父模块中添加依赖，在子模块中引用，可以实现依赖更好的管理以及共用，方法如下：

父模块pom

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>2.9.2</version>

</dependency>



<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>2.9.2</version>

</dependency>

</dependencies>

</dependencyManagement>

注意在 <dependencies>外层添加<dependencyManagement>，用于说明内部的依赖由父模块管理，否则子模块无法获取此依赖。

子模块pom

<dependencies>

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

</dependency>

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

</dependency>

</dependencies>

可以看到子模块中仅仅是引用而不必写其版本号，因为父模块已经声明了。

4. 由于子模块创建的是maven项目，所以如果需要其实现spring boot的功能（如 web等），需要单独为其添加相关依赖。

同样可以看到在这里是不用为其注明版本号的，但是如果直接import就会发现此依赖导入失败，去查看父依赖就会看到父依赖也没有自动添加版本号配置，此时在父依赖添加版本号（版本号保持与springboot的版本号一致即可）即可

5. 配置信息配置完毕后，为swagger创建swagger page类，在config包下创建SwaggerConfig类，内容如下：

@Configuration

@EnableSwagger2

public class SwaggerConfig extends WebMvcConfigurationSupport {

@Bean

public Docket createRestApi() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

.select()

//引入需要创建接口文档的包

.apis(RequestHandlerSelectors.basePackage("com.tuhu.xianwenzhang.controller"))

.paths(PathSelectors.any())

.build();

}

//初始化swagger-ui.html界面

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title("Spring Boot Swagger2 学习")

.description("更多内容请详见代码")

.termsOfServiceUrl("http://blog.youkuaiyun.com/cwenao")

.version("0.5.0")

.build();

}

//在高版本中需要添加下列代码，否则报错 “ No mapping found for HTTP request with URI [/csrf] in DispatcherServlet with name 'dispatcherServlet‘ “ 我这儿用的是2.9.2版本，其他版本自行测试

@Override

public void addResourceHandlers(ResourceHandlerRegistry registry) {

registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");

registry.addResourceHandler("swagger-ui.html")

.addResourceLocations("classpath:/META-INF/resources/");

registry.addResourceHandler("/webjars/**")

.addResourceLocations("classpath:/META-INF/resources/webjars/");

}

}

之后再controller包下创建SwaggerController类，添加内容

@RestController

@Api(value = "swagger学习实现")

public class SwaggerController {

/**

* 若此处无映射地址@RequestMapping("/testSwagger")，swagger报错找不到URI

*/

@ApiOperation("显示swagger")

@PostMapping(value= "/testSwagger", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)

public User showSwagger(@ApiParam(name = "user", value = "修改权限接口", required = true)

@RequestBody User user) {

return user;

}

}

此时swagger的编写基本完成，但是由于子模块创建时是maven项目，所以其不拥有启动类，需要手动添加，在controller的上一级目录下创建类SwaggerApplication类作为其启动类，内容为

@EnableWebMvc

@SpringBootApplication

public class SwaggerApplication {

public static void main(String[] args) {

SpringApplication.run(SwaggerApplication.class, args);

}

}

其中的注解必须写，否则会报错。

然后右键运行。