[Swagger]swagger构建你的api文档

ゞ浴缸里的玫瑰 2022-04-12 07:40 377阅读 0赞

Swagger能成为最受欢迎的REST APIs文档生成工具之一，有以下几个原因：

Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。  
Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。  
Swagger 文件可以在许多不同的平台上从代码注释中自动生成。  
Swagger 有一个强大的社区，里面有许多强悍的贡献者。

下面开始配置教程  
文件:[https://download.csdn.net/download/drdongshiye/10822532][https_download.csdn.net_download_drdongshiye_10822532]  
1.[swagger editor][]  
下载可用的Swagger spec(规范)配置文件,一般默认yml文件(使用 YML 替换JSON。 YML 句法比 JSON 可读性高。使用 YML ，空格很重要。新段落需要缩进两个空格。冒号表示个对象。连字符代表一个 sequence 或者 list （像一个 array）。如果你下载这个文件而不是复制粘贴，你基本不会碰到空格问题)  
Swagger editor 告诉你文件如何被输出，你也可以看到验证出来的错误。没有这个在线编辑器，你只能在运行代码的时候才能知道 YML 句法是否有效 （并且看到错误提示， YAML 文件也不能被正确解析）。

将该文件下载到本地 File->save as YAML文件  
注:在swagger editor 可以校验文件是否正确  
2.配置swagger ui  
1、Github: Swagger UI。下载、解压。只需要用到 dist 文件夹。除非你想重新生成 dist 中的文件，才会用到别的。  
2、打开 dist > index.html  
3、找到：url = “[http://petstore.swagger.io/v2/swagger.json][http_petstore.swagger.io_v2_swagger.json]”;  
4、值改成 swagger.yaml 的路径  
5、保存打开index.html

\------------------------以上内容即可完成swagger基本使用--------------------------------

上传文件到 web 主机  
除了本地浏览 Swagger 文件，你也可以使用 XAMPP 在本地运行一个 web 服务器  
1、下载安装XAMPP  
2、在你的应用程序文件夹中打开 XAMPP 文件夹，启动 manager-osx 控制台  
3、单击 Manage Servers tab  
4、选择 Apache Web Server 单击 Start  
5、打开 XAMPP 中的 htdocs 文件夹。如果是Mac，通常在 /Applications/XAMPP/xamppfiles/htdocs。  
6、将 dist 文件夹拖到此处  
7、在你的浏览器中浏览 localhost/dist  
就可以看到 Swagger UI的展示。  
体验 Swagger UI  
1、用浏览器浏览 Swagger UI。  
2、在右上角，单击 Authorize 并且输入你的 Mashape API Key。如果你没有 Mashape API Key，你可以3、使用 EF3g83pKnzmshgoksF83V6JB6QyTp1cGrrdjsnczTkkYgYrp8p。  
4、去 Google Maps 搜索一个地址。  
5、从 URL 中去获取经纬度，将其插入到你的 Swagger UI中（比如：1.3319164 for lat, 103.7231246 for lng）  
6、单击 Try it out。  
如果成功，你应该可以看到 response body 的响应：9 c, Mostly Cloudy at South West, Singapore  
如果你看到了Not supported，尝试调整经纬度。  
如果你刷新了界面，你要重新输入 API Key。

参考:[https://www.cnblogs.com/JoiT/p/6378086.html][https_www.cnblogs.com_JoiT_p_6378086.html]

[https_download.csdn.net_download_drdongshiye_10822532]: https://download.csdn.net/download/drdongshiye/10822532
[swagger editor]: http://editor.swagger.io/
[http_petstore.swagger.io_v2_swagger.json]: http://petstore.swagger.io/v2/swagger.json
[https_www.cnblogs.com_JoiT_p_6378086.html]: https://www.cnblogs.com/JoiT/p/6378086.html