springboot整合swagger

最新推荐文章于 2025-03-01 00:19:35 发布

那只猫哭了

最新推荐文章于 2025-03-01 00:19:35 发布

阅读量1k

点赞数

分类专栏： spring

本文链接：https://blog.youkuaiyun.com/caoyang0105/article/details/82785475

版权

spring 专栏收录该内容

9 篇文章

订阅专栏

本文详细介绍如何在SpringBoot项目中集成Swagger2，包括添加依赖、配置类编写、注解使用等步骤，帮助快速生成RESTful API文档。

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

swagger

swagger是一个流行的API开发框架，这个框架以“开放API声明”（OpenAPI Specification，OAS）为基础，
对整个API的开发周期都提供了相应的解决方案，是一个非常庞大的项目（包括设计、编码和测试，几乎支持所有语言）。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
总体目标是使客户端和文件系统作为服务器以同样的速度来更新。
文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

springboot + swagger

现在pom文件中添加swagger依赖

<!--swagger-->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.6.1</version>
		</dependency>

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

接下来就是对swagger进行配置

@Configuration
@EnableSwagger2
public class SwaggerUtil {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //.apis(RequestHandlerSelectors.basePackage("com.iresearch.cms.controller"))
                //这个是扫描有Api注解的类
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格，http://blog.youkuaiyun.com/saytime")
                .termsOfServiceUrl("http://blog.youkuaiyun.com/saytime")
                .version("1.0")
                .build();
    }
}

其中 .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) 这块是重点，主要扫描有@Api注解的类，也可以使用 .apis(RequestHandlerSelectors.basePackage("com.iresearch.cms.controller")) 这个代码，这个是指定哪个包。

接下来就是在controller中使用了

最后就是要在启动类中添加@EnableSwagger2这个注解，表示开启swagger

运行项目之后，访问 http://localhost:8080/swagger-ui.html

就可以查看文档

swagger注解

@Api：描述controller
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数例如：@ApiImplicitParams({@ApiImplicitParam(name = "username",value = "用户名",required = true,dataType = "String"),@ApiImplicitParam(name = "password",value = "密码",required = true,dataType = "String")})