文章详情

短信预约-IT技能 免费直播动态提醒

请输入下面的图形验证码

提交验证

短信预约提醒成功

前后端分离项目必备——自动生成API文档神器Swagger

2024-11-30 08:11

关注

然而Spring MVC并没有提供一个方便且标准的方式来描述和文档化API,这给API的管理和维护带来了一定的困难。为了解决这个问题,一个名为Swagger的项目诞生了。Swagger是由Tony Tam在2010年创建的一个开源项目,旨在为RESTful API提供一个规范且完整的框架4。Tony Tam是一个资深的Java开发者,他在使用Spring MVC开发API时感受到了它的优点和缺点,所以他决定创建一个可以与Spring MVC无缝集成的工具,来帮助开发者更好地设计、描述、调用和可视化API。

Swagger项目很快就得到了开源社区和业界的认可和支持,成为了最流行的API开发工具之一。Swagger项目也不断地演进和完善,涵盖了各种语言和框架,如Python, Ruby, Node.js, Django, Rails等。Swagger项目也不断地与其他标准和工具集成,如OpenAPI Specification, Postman, Apigee等。

Swagger的作用

Swagger的主要作用是为RESTful风格的Web服务提供一个标准且完整的框架,包括以下几个方面:

Swagger的好处

Swagger作为一个流行且成熟的API开发工具,它有以下几个好处:

Swagger项目现在已经成为了一个庞大且活跃的生态系统,包括以下几个部分:

Springboot使用Swagger3生成API文档

步骤说明

注意:

对于2.x.x版本,访问地址为:http://localhost:8080/{context-path}/swagger-ui.html

对于3.x.x版本,访问地址为:http://localhost:8080/{context-path}/swagger-ui/index.html

其中,localhost是你的本地主机名,8080是你的项目端口号,{context-path}是你的项目上下文路径。你需要根据你的实际情况来替换这些参数。

例如,如果你的项目端口号是8081,上下文路径是demo,Swagger版本是3.0.0,那么你可以访问以下地址来查看Swagger UI界面:

http://localhost:8081/demo/swagger-ui/index.html

pom.xml文件


    
    
        org.springframework.boot
        spring-boot-starter-web
    
    
    
        org.springdoc
        springdoc-openapi-ui
        1.5.12
    

配置类

// 配置类
@Configuration
@OpenAPIDefinition(
        info = @Info(
                title = "Swagger3示例API",
                description = "这是一个使用Swagger3来开发Spring Boot应用中的API的示例",
                version = "1.0",
                contact = @Contact(
                        name = "张三",
                        email = "zhangsan@example.com",
                        url = "1"
                )
        )
)
public class SwaggerConfig {
}

控制器类

// 控制器类
@RestController
@RequestMapping("/user")
@Tag(name = "用户管理API", description = "提供用户相关的操作")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "根据ID查询用户信息", description = "返回用户实体对象")
    @ApiResponse(responseCode = "200", description = "查询成功")
    @ApiResponse(responseCode = "404", description = "用户不存在")
    public User getUserById(@PathVariable("id") @Parameter(description = "用户ID", required = true, example = "1") Long id) {
        // 模拟查询数据库
        User user = new User();
        user.setId(id);
        user.setName("张三");
        user.setAge(18);
        return user;
    }

    @PostMapping("/")
    @Operation(summary = "添加用户信息", description = "返回添加结果")
    @ApiResponse(responseCode = "200", description = "添加成功")
    @ApiResponse(responseCode = "400", description = "参数错误")
    public String addUser(@RequestBody @Parameter(description = "用户实体对象", required = true) User user) {
        // 模拟插入数据库
        return "添加成功";
    }

}

用户实体类

// 用户实体类
@Schema(name = "用户实体类", description = "用户的基本信息")
public class User {

    @Schema(description = "用户ID")
    private Long id;

    @Schema(description = "用户姓名")
    private String name;

    @Schema(description = "用户年龄")
    private Integer age;

    // 省略getter和setter方法
}

Swagger注解总结:

Swagger注解有以下几种类型:

下面是一个对Swagger常用注解的总结表格:

来源:今日头条内容投诉

免责声明:

① 本站未注明“稿件来源”的信息均来自网络整理。其文字、图片和音视频稿件的所属权归原作者所有。本站收集整理出于非商业性的教育和科研之目的,并不意味着本站赞同其观点或证实其内容的真实性。仅作为临时的测试数据,供内部测试之用。本站并未授权任何人以任何方式主动获取本站任何信息。

② 本站未注明“稿件来源”的临时测试数据将在测试完成后最终做删除处理。有问题或投稿请发送至: 邮箱/279061341@qq.com QQ/279061341

软考中级精品资料免费领

  • 历年真题答案解析
  • 备考技巧名师总结
  • 高频考点精准押题
  • 2024年上半年信息系统项目管理师第二批次真题及答案解析(完整版)

    难度     813人已做
    查看
  • 【考后总结】2024年5月26日信息系统项目管理师第2批次考情分析

    难度     354人已做
    查看
  • 【考后总结】2024年5月25日信息系统项目管理师第1批次考情分析

    难度     318人已做
    查看
  • 2024年上半年软考高项第一、二批次真题考点汇总(完整版)

    难度     435人已做
    查看
  • 2024年上半年系统架构设计师考试综合知识真题

    难度     224人已做
    查看

相关文章

发现更多好内容

猜你喜欢

AI推送时光机
位置:首页-资讯-后端开发
咦!没有更多了?去看看其它编程学习网 内容吧
首页课程
资料下载
问答资讯