Swagger 详解

已于 2024-04-09 11:04:49 修改
阅读量244 收藏
点赞数 2
文章标签： java
于 2024-04-03 16:35:53 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.youkuaiyun.com/ToBeMaybe_/article/details/137349713
版权

Swagger简介
Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。总体来说，Swagger提供了一套标准的注解，开发者可以通过这些注解来描述他们的API，然后Swagger可以根据这些注解生成可交互的API文档。

swagger2 最常用的5个注解

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
 
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
 
 
其它若干
@ApiResponse：HTTP响应其中1个描述
 
@ApiResponses：HTTP响应整体描述
 
@ApiClass
 
@ApiError
 
@ApiErrors
 
@ApiParamImplicit
 
@ApiParamsImplicit

swagger3的注解与swagger2相差很多，也兼容了swagger2的注解，区别如下：

swagger2swagger3说明
@Api@TagController类上
@ApiOperation@OperationController方法上
@ApiModel@SchemaDTO类上
@ApiModelProperty@SchemaDTO方法上

在这里插入图片描述

Swagger2 关于Map参数在API文档中展示详细参数以及参数说明
hellopeng1的博客
08-30 13万+
前言 本文主要解决的问题是 Swagger2 （SpringFox）关于Map参数生成的API文档中没有详细Json结构说明，问题如下图所示： 此种方式生成的Api文档中的请求参数如下: 如果是这样的参数类型的会让查看API的人员无法清晰的知道如何请求API文档。当然Swagger2 根据这种情况也给出了解决方案： @ApiOperation(value = "not...
SpringBoot整合Swagger详解
kiingking的博客
07-10 152
在Spring Boot项目中整合Swagger（现在通常指的是SpringDoc，因为它基于OpenAPI 3.0标准）。
Swagger 常用注解说明
yumu1234567的博客
04-12 957
Swagger 常用注解说明 1.常用注解 @Api：修饰整个类，描述 Controller 的作用 @ApiOperation：描述一个类的一个方法，或者说一个接口 @ApiParam：单个参数描述 @ApiModel：用对象来接收参数 @ApiProperty：用对象接收参数时，描述对象的一个字段 @ApiResponse：HTTP 响应其中 1 个描述 @ApiResponses：HTTP...
Swagger入门教程
weixin_34166847的博客
11-28 425
关于 Swagger Swagger能成为最受欢迎的REST APIs文档生成工具之一，有以下几个原因： Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。 Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。 Swagger 文件可以在许多不同的平台上从代码注释中自动生成。 Swagger 有一个强大的社区，里面有许多强悍的贡...
SpringBoot-----集成Swagger
qq_44236958的博客
04-18 1201
SpringBoot集成Swagger 文章目录SpringBoot集成Swagger前后端分离:产生的问题:SwaggerSpringBoot集成Swagger配置Swagger配置扫描接口配置Swagger开关配置API分组实体配置常用注解总结 简介: 前后端分离: 前端 ->前端控制层,视图 后端 ->后端控制层,服务层,数据访问层 前后端通过API进行交互 前后端相对独立且松耦合 产生的问题: 前后端集成,前端或者后端无法左到"“及时协商,今早解决”",最终问题集中爆发 Swag
Swagger介绍及使用
River的博客
11-13 2842
什么是Swagger： Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。通俗的讲，Swagger 就是将项目中所有接口（想要暴露出去的接口）展现在页面上，并且可以进行接口调用和测试的服务。 好处： 1、后端程序员就不需要专门为前端使用者编写专门的接口文档； 2、当接口更新之后，只需要修改代码中的 Swagger 描述就可以实时生成新的接口文档了； 3、可以直接进行接口调用，降低了项目开发阶段的调试成本。 Swagger的使用： 1、先
手把手教会如何掌握Swagger
HSQdePYZ的博客
09-06 276
Swagger是一个用于设计、构建、文档化和消费RESTful Web服务的开源工具集。它的主要目标是简化API的开发和维护，同时提供自动生成的交互式API文档。Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。
SpringBoot 14、终极整合 Swagger
sowhat
08-29 960
整合 Swagger
Swagger详解（SpringBoot Swagger集成）.docx
06-27
Swagger 是一个强大的工具，用于构建、管理和维护 RESTful 风格的 Web 服务。它遵循 OpenAPI 规范，提供了全面的框架，包括生成 API 文档、接口测试和可视化的功能。Swagger 的核心目标是确保客户端和服务器的同步...
Springboot集成Swagger详解经过
12-21
在本文中，我们将深入探讨如何在Spring Boot应用中集成Swagger，并详细解析集成过程及关键配置。Swagger是一款强大的API文档工具，它可以自动生成RESTful API的文档，帮助开发者更轻松地管理和测试API。以下是对...
SpringBoot集成Swagger详解：自动化API文档管理轻松搞定
[SpringBoot集成Swagger详解：自动化API文档管理轻松搞定](https://www.apriorit.com/wp-content/uploads/2022/10/benefits-of-using-swagger-in-api-development.png) # 摘要 随着微服务架构的流行，API文档的生成...
API中文文档：Swagger详解
qf2019的博客
10-27 1296
目前来说，在 Java 领域使用 Springboot 构建微服务是比较流行的，在构建微服务时，我们大多数会选择暴漏一个 REST API 以供调用。又或者公司采用前后端分离的开发模式，让前端和后端的工作由完全不同的工程师进行开发完成。不管是微服务还是这种前后端分离开发，维持一份完整的及时更新的 REST API 文档，会极大的提高我们的工作效率。而传统的文档更新方式(如手动编写)，很难保证文档的及时性，经常会年久失修，失去应有的意义。因此选择一种新的 API 文档维护方式很有必要，这也是这篇文章要介绍的内
Swagger-的使用(详细教程)
热门推荐
xhmico的博客
06-19 6万+
作为后端开放人员，最烦的事就是自己写接口文档和别人没有写接口文档，不管是前端还是后端开发，多多少少都会被接口文档所折磨，前端会抱怨后端没有及时更新接口文档，而后端又会觉得编写接口文档太过麻烦。Swagger 可以较好的接口接口文档的交互问题，以一套标准的规范定义接口以及相关的信息，就能做到生成各种格式的接口文档，生成多种语言和客户端和服务端的代码，以及在线接口调试页面等等。只需要更新 Swagger 描述文件，就能自动生成接口文档，做到前端、后端联调接口文档的及时性和便利性。官网：https://swagg
Swagger
cts529269539的专栏
01-29 2895
1：认识Swagger Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。  作用：     1. 接口的文档在线自动生成。     2. 功能测试。  Swagger是一组开源项目，其中主要要项目如
swagger简介
weixin_52639224的博客
03-11 1万+
一、swagger的作用 根据在代码中使用自定义的注解来生成接口文档，这个在前后端分离的项目中很重要。这样做的好处是 在开发接口时可以通过swagger将接口文档定义好，同时也方便以后的维护。 在没有swagger之前，我们可以使用word，excel等功能来书写接口定义文档，但又有一个弊端，即： 在接口发送改变时需要及时的同步接口文档，否则实际的接口与接口文档不相符，则接口文件就失去了作用，甚至会起到反作用。 二、swagger的优点 号称时最流行的API框架 接口文档在线生成.
初识C++：模版
2401_87194328的博客
05-23 833
该博客主要讲解模版的相关内容
springboot--实战--大事件--用户接口开发
最新发布
m0_73856804的博客
05-27 1238
定义了一种简洁的、自包含的格式，用于通信双方以JSON数据格式安全的传输信息。组成：第一部分：Header（头），记录令牌类型、签名算法等。例如,算法用于防篡改第二部分：Payload（有效载荷），携带一些自定义信息，默认信息。例如。而外在表示为一段无规律的64个可打印字符原因：借助base64编码方式（Base64：是一种基于64个可打印字符（A-Z a-z 0-9 + /）来表示二进制数据的编码方式）来完成，将json字符串变为64个可打印字符，
canal实现mysql数据同步
那些乐趣的博客
05-23 1889
1、canal下载进入页面可以选择需要安装的版本下载canal.deployer-1.1.8.tar.gz和canal.admin-1.1.8.tar.gz2、mysql同步用户创建和授权在canal-admin解压文件的conf中有一个canal_manager.sql，导入到master数据库3、canal admin安装和启动把canal.admin-1.1.8.tar.gz上传到linux解压 tar -zvxf canal.admin-1.1.8.tar.gz。
【如何做好一份技术文档？】用Javadoc与PlantUML构建高质量技术文档（API文档自动化部署）
一个XR（AR|VR|MR）程序猿的博客（EQ-雪梨蛋花汤）
05-24 2538
在本指南中，我们将深入探讨如何使用Javadoc和PlantUML工具，围绕Java项目生成专业的类图、流程图与结构化的API文档，并整合成完整的开发流程与快速开始模板，帮助技术团队高效构建可持续维护的知识资产。
express swagger注解详解
01-01
### Express 中使用 Swagger 注解的方法 在 Express 中集成 Swagger 可以为 API 提供强大的自动生成文档功能以及在线测试工具。通过 `swagger-jsdoc` 和 `swagger-ui-express` 这两个包可以轻松实现这一目标。 #### 安装依赖库 为了使项目能够识别并解析注释，需先安装必要的 NPM 包： ```bash npm install swagger-jsdoc swagger-ui-express --save ``` 此命令会下载所需的模块来生成 JSDoc 风格的注释，并将其转换成 Swagger 文档格式[^1]。 #### 创建 Swagger 配置文件 定义一个名为 `swagger.config.js` 的配置文件用于指定 API 版本、标题以及其他元数据信息: ```javascript const swaggerJSDoc = require('swagger-jsdoc'); // Swagger configuration options module.exports = { definition: { openapi: '3.0.0', info: { title: 'Express API with Swagger', version: '1.0.0' } }, apis: ['./routes/*.js'] // Path to the API docs files }; ``` 上述代码片段展示了如何设置 OpenAPI 规范版本和基本信息字段，同时也指定了要扫描哪些路径下的 JavaScript 文件以提取注释。 #### 编写带注解的路由函数 接下来，在具体的路由处理器中加入相应的注释标签以便于后续生成详细的 API 描述。下面是一个简单的 GET 请求例子： ```javascript /** * @swagger * /users/{id}: * get: * summary: Returns a single user by ID. * tags: [Users] * parameters: * - in: path * name: id * schema: * type: string * required: true * description: User ID * responses: * 200: * description: Successful response */ router.get('/:id', (req, res) => { const { id } = req.params; // Fetch and send back data... }); ``` 这段注释描述了一个获取特定用户的 RESTful 接口，其中包含了请求参数说明及可能返回的状态码等重要细节。 #### 启动 Swagger UI 最后一步是在应用启动时加载 Swagger UI 并挂载到某个 URL 路径下方便访问。这通常会在项目的入口文件 (`app.js`) 或者专门负责初始化中间件的地方完成： ```javascript const express = require('express'); const app = express(); const swaggerUi = require('swagger-ui-express'); const swaggerDocument = require('./swagger.json'); // Generated from swagger-config.js // Mounting swagger ui at '/docs' endpoint app.use('/docs', swaggerUi.serve); app.get('/docs', swaggerUi.setup(swaggerDocument)); // Start server listening on port 3000 app.listen(3000, () => console.log('Server started')); ``` 这样当服务器运行起来之后就可以通过浏览器打开 `/docs` 页面浏览完整的 API 文档了。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值