百度360必应搜狗淘宝本站头条
当前位置:网站首页 > 技术分类 > 正文

SpringBoot2.0整合Api文档Swagger

ztj100 2025-05-08 08:09 58 浏览 0 评论

前言

最近在整理Github的仓库时,看到以前大学的时候写了个SpringBoot和Swagger的demo,想了一下最后决定写一篇文章,记录一下。

Swagger简介

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码,允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

创建工程

SpringBoot的版本是2.0.8,Swagger的版本是2.9.2

	<parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.0.8.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
	<dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

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

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

Swagger的配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        //主要api配置机制初始化为swagger规范2.0
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.msr.demo.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("msr", "www.baidu,com", "maisrcn@qq.com");
        return new ApiInfoBuilder()
                // 标题
                .title("Spring Boot中使用Swagger2构建RESTful API")
                // 描述信息
                .description("rest api 文档构建利器")
                //服务网址
                .termsOfServiceUrl("http://localhost:8080")
                //版本号
                .version("1.0")
                .contact(contact)
                .build();
    }
}

Controller控制层

Swagger主要是在控制层上使用,通过一些注解来为接口提供API文档。下述的代码中主要使用的注解为这两个@ApiOperation和 @ApiImplicitParam这两个,@ApiOperation注解来给API增加说明并通过@ApiImplicitParams注解来给参数增加说明

下面试一些Swagger的常用的注解,更详细的可以查看官方的文档。

  • @Api:将类标记为Swagger资源
  • @ApiImplicitParam:表示API操作中的单个参数
  • @ApiImplicitParams:一个包装器,允许列出多个ApiImplicitParam对象
  • @ApiModel:提供有关Swagger模型的其他信息,比如描述POJO对象
  • @ApiModelProperty: 添加和操作模型属性的数据
  • @ApiOperation: 描述针对特定路径的操作或通常是HTTP方法
  • @ApiParam: 为操作参数添加其他元数据
  • @ApiResponse: 描述操作的可能响应
  • @ApiResponses: 一个包装器,允许列出多个ApiResponse对象
  • @Authorization: 声明要在资源或操作上使用的授权方案
  • @AuthorizationScope: 描述OAuth2授权范
  • @ResponseHeader: 表示可以作为响应的一部分提供的标头。
  • @ApiProperty: 描述POJO对象中的属性值
  • @ApiError : 接口错误所返回的信息
  • ...
@Slf4j
@Api(tags = "用户相关相关的API")
@RestController
public class UserController {

    @ApiOperation(value = "获取用户信息",notes="添加用户信息")
    @PostMapping("/user")
    public String addUser(@RequestBody User user) {
        log.info("POST请求,接收到参数:{}", user.toString());
        return user.toString();
    }

    @ApiOperation(value = "更新用户", notes = "根据User对象更新用户")
    @ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
    @PutMapping("/user")
    public boolean updateUser(@RequestBody User user) {
        log.info("UPDATE请求,请求参数:{}", user);
        return true;
    }

    @ApiOperation(value = "删除用户", notes = "根据User对象删除用户")
    @ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
    @DeleteMapping("/user")
    public boolean deleteUser(@RequestBody User user) {
        log.info("DELETE请求,请求参数:{}", user);
        return true;
    }


    @ApiOperation(value = "获取用户列表", notes = "根据User对象查询用户信息")
    @ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
    @GetMapping("/user")
    public User findByUser(User user) {
        log.info("GET请求,请求参数:{}", user);
        return User.builder()
                .id(1)
                .age(18)
                .name("小明")
                .build();
    }
}

实体类

@ApiModel("用户实体")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class User implements Serializable {
	@ApiModelProperty("用户ID")
    private Integer id;
    @ApiModelProperty("用户名")
    private String name;
    @ApiModelProperty("登录密码")
    private String password;
    @ApiModelProperty("年龄")
    private Integer age;
}

启动类

@SpringBootApplication
public class SwaggerDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerDemoApplication.class, args);
    }

}

测试

启动程序,浏览器访问
http://localhost:8080/swagger-ui.html

点开UserController和Models可以看到在代码中的配置

选择要测试的接口,点击Try it out。输入参数,

总结

其实,Swagger的注解很多,当把一个API描述好之后,会发现方法上多了一堆的注解。对于我个人来说有点不舒服,感觉有点侵略性的感觉。对于API文档,目前有很多的项目,感觉用起来也不错。

作者:8aceSuper
链接:
https://juejin.cn/post/6977369983928139812

相关推荐

其实TensorFlow真的很水无非就这30篇熬夜练

好的!以下是TensorFlow需要掌握的核心内容,用列表形式呈现,简洁清晰(含表情符号,<300字):1.基础概念与环境TensorFlow架构(计算图、会话->EagerE...

交叉验证和超参数调整:如何优化你的机器学习模型

准确预测Fitbit的睡眠得分在本文的前两部分中,我获取了Fitbit的睡眠数据并对其进行预处理,将这些数据分为训练集、验证集和测试集,除此之外,我还训练了三种不同的机器学习模型并比较了它们的性能。在...

机器学习交叉验证全指南:原理、类型与实战技巧

机器学习模型常常需要大量数据,但它们如何与实时新数据协同工作也同样关键。交叉验证是一种通过将数据集分成若干部分、在部分数据上训练模型、在其余数据上测试模型的方法,用来检验模型的表现。这有助于发现过拟合...

深度学习中的类别激活热图可视化

作者:ValentinaAlto编译:ronghuaiyang导读使用Keras实现图像分类中的激活热图的可视化,帮助更有针对性...

超强,必会的机器学习评估指标

大侠幸会,在下全网同名[算法金]0基础转AI上岸,多个算法赛Top[日更万日,让更多人享受智能乐趣]构建机器学习模型的关键步骤是检查其性能,这是通过使用验证指标来完成的。选择正确的验证指...

机器学习入门教程-第六课:监督学习与非监督学习

1.回顾与引入上节课我们谈到了机器学习的一些实战技巧,比如如何处理数据、选择模型以及调整参数。今天,我们将更深入地探讨机器学习的两大类:监督学习和非监督学习。2.监督学习监督学习就像是有老师的教学...

Python教程(三十八):机器学习基础

...

Python 模型部署不用愁!容器化实战,5 分钟搞定环境配置

你是不是也遇到过这种糟心事:花了好几天训练出的Python模型,在自己电脑上跑得顺顺当当,一放到服务器就各种报错。要么是Python版本不对,要么是依赖库冲突,折腾半天还是用不了。别再喊“我...

超全面讲透一个算法模型,高斯核!!

...

神经网络与传统统计方法的简单对比

传统的统计方法如...

AI 基础知识从0.1到0.2——用“房价预测”入门机器学习全流程

...

自回归滞后模型进行多变量时间序列预测

下图显示了关于不同类型葡萄酒销量的月度多元时间序列。每种葡萄酒类型都是时间序列中的一个变量。假设要预测其中一个变量。比如,sparklingwine。如何建立一个模型来进行预测呢?一种常见的方...

苹果AI策略:慢哲学——科技行业的“长期主义”试金石

苹果AI策略的深度原创分析,结合技术伦理、商业逻辑与行业博弈,揭示其“慢哲学”背后的战略智慧:一、反常之举:AI狂潮中的“逆行者”当科技巨头深陷AI军备竞赛,苹果的克制显得格格不入:功能延期:App...

时间序列预测全攻略,6大模型代码实操

如果你对数据分析感兴趣,希望学习更多的方法论,希望听听经验分享,欢迎移步宝藏公众号...

AI 基础知识从 0.4 到 0.5—— 计算机视觉之光 CNN

...

取消回复欢迎 发表评论: