讯享网

 <p>据说有个说法很流行，程序员最讨厌两件事情，1.写注释写文档； 2.别人不写注释、不写文档。</p><p>  </p><p>为什么这样说？因为管理文档注释比较麻烦，经常会出现 <strong>API</strong> 更新了，文档还是老的，各种同步不一致的情况。造成很多问题，从而耽搁彼此的时间，所以大家不太喜欢进行写文档注释。</p><p>  </p><p>而之所以使用 <strong>swagger</strong> 主要是 swagger 它可以降低我们前后端开发文档同步问题，swagger 可以从我们代码注释里面自动生成 API 文档，以此方便前端对接使用。Swagger UI 是允许开发团队和终端用户使用，接口可视化，交互便捷。</p><p>  </p><p>无论你是 Design 优先或 者Code 优先，你最终都会得到一个 Swagger/OpenApi 文件。这就是约定，这种约定很难让你看懂。为什么不给他们看起来好看点，于是有了 Swagger UI。 当然还有其他的 UI 工具，比如说 ReDoc， 但是我比较推荐 Swagger UI， 实话说，他最好看。</p><p>  </p><p><strong>Swagger 文件示例</strong></p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://apifox.com/apiskills/content/images/2023/07/image-87.png" class="kg-image" alt loading="lazy" width="1280" height="891" srcset="https://apifox.com/apiskills/content/images/size/w600/2023/07/image-87.png 600w, https://apifox.com/apiskills/content/images/size/w1000/2023/07/image-87.png 1000w, https://apifox.com/apiskills/content/images/2023/07/image-87.png 1280w" sizes="(min-width: 720px) 720px"><figcaption>Swagger 文件示例</figcaption></figure><p>刚说到 Redoc， 也同样是一个 Swagger 可视化工具，长得有点小清新，还是 Swagger UI 比较靓。</p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://apifox.com/apiskills/content/images/2023/07/image-88.png" class="kg-image" alt="使用 Swagger UI" loading="lazy" width="1280" height="674" srcset="https://apifox.com/apiskills/content/images/size/w600/2023/07/image-88.png 600w, https://apifox.com/apiskills/content/images/size/w1000/2023/07/image-88.png 1000w, https://apifox.com/apiskills/content/images/2023/07/image-88.png 1280w" sizes="(min-width: 720px) 720px"><figcaption>Redoc UI</figcaption></figure><p>以下是 Swagger 的样子</p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://apifox.com/apiskills/content/images/2023/07/image-89.png" class="kg-image" alt="使用 Swagger UI" loading="lazy" width="1280" height="661" srcset="https://apifox.com/apiskills/content/images/size/w600/2023/07/image-89.png 600w, https://apifox.com/apiskills/content/images/size/w1000/2023/07/image-89.png 1000w, https://apifox.com/apiskills/content/images/2023/07/image-89.png 1280w" sizes="(min-width: 720px) 720px"><figcaption>Swagger UI</figcaption></figure><p>是不是很靓？</p><figure class="kg-card kg-image-card"><img src="https://apifox.com/apiskills/content/images/2023/07/image-90.png" class="kg-image" alt="使用 Swagger UI" loading="lazy" width="259" height="194"></figure><p>这个 Swagger UI 具有可定制性，你可以根据自己的需求对 UI 进行调整和美化，甚至可以集成其他 Swagger 增强UI，如 SwaggerBootstrapUI 和 Knife4j。</p><p> </p><p>你可以在 <strong>Swagger Hub</strong> 直接体验</p><p> </p><p> </p><p>Swagger UI 作为最流行的 API 可视化工具， 很多 Web 框架都内置了 Swagger UI，比如说 <strong>fastapi</strong> 、 <strong>flask</strong> , 我们可以通过扩展的方式引入。</p><p>  </p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://apifox.com/apiskills/content/images/2023/07/image-91.png" class="kg-image" alt="Swagger UI documentation使用 Swagger UI" loading="lazy" width="1280" height="761" srcset="https://apifox.com/apiskills/content/images/size/w600/2023/07/image-91.png 600w, https://apifox.com/apiskills/content/images/size/w1000/2023/07/image-91.png 1000w, https://apifox.com/apiskills/content/images/2023/07/image-91.png 1280w" sizes="(min-width: 720px) 720px"><figcaption>Swagger UI documentation</figcaption></figure><p>其他开发语言也是同理，比如说 <strong>Graphul</strong> 一个 Rust Web Framework，无缝嵌入 Swagger UI。</p><p>  </p><p>感觉现在 Web 框架越来越卷了，好多好东西开箱即用， 生产率又提高了有木有~~~ 所以每天能早点下班了吧。</p><figure class="kg-card kg-image-card"><img src="https://apifox.com/apiskills/content/images/2023/07/image-92.png" class="kg-image" alt="使用 Swagger UI" loading="lazy" width="300" height="300"></figure><p> </p><p></p><p>虽然大家都推荐将 Swagger 接口文档服务部署在开发环境，但是由于现公司前后端开发人员异地办公，我还是倾向于将 swaggo 服务部署在生产环境。加上个简单的账号密码访问限制即可。</p><p>  </p><p>基于 Token 的鉴权</p><p> </p><p>基于 Token 的鉴权是一种比较常见的鉴权方式。具体来说，可以通过在请求头中添加一个 Token，来验证请求是否合法。可以在 Nginx 的配置文件中添加以下内容来实现基于 Token 的鉴权： </p><pre></pre><p>上述代码中，表示请求头中的 Authorization 字段，而则是指定的Token 值。如果请求头中的 Authorization 字段与指定的 Token 不一致，Nginx 将返回 401 错误。</p><p>  </p><p>当然还有其他保护方式，如果放在外网访问一定要注意。另外也可以集成 OKTA 鉴权，也可以用 Github 登录，大家可以折腾下。</p><p> </p><p>如果想分享 API 给团队， 我建议使用 <strong>Apifox</strong>， 使用 Apifox 邀请和带密码分享链接都非常安全。无论是 API 设计、调试、测试、文档分享等等都可以在 Apifox 上全部搞定。</p><figure class="kg-card kg-image-card"><img src="https://apifox.com/apiskills/content/images/2024/10/" class="kg-image" alt="Swagger UI" loading="lazy" width="2000" height="1147" srcset="https://apifox.com/apiskills/content/images/size/w600/2024/10/ 600w, https://apifox.com/apiskills/content/images/size/w1000/2024/10/ 1000w, https://apifox.com/apiskills/content/images/size/w1600/2024/10/ 1600w, https://apifox.com/apiskills/content/images/size/w2400/2024/10/ 2400w" sizes="(min-width: 720px) 720px"></figure><p>所以别再乱发 swagger.json 文件了！很难找得到～～</p><p>  </p><p>还是推荐 Apifox，一个 API 文档、测试和自动化工具的平台。包括了模拟数据生成、在线文档共享和自动测试管理， 非常专业的 API 工具。</p><p>  </p><p><strong><strong><em><em>知识扩展：</em></em></strong></strong></p><ul><li><em><em><strong><strong>如何使用 Swagger Editor 编写 API 文档</strong></strong></em></em></li><li><strong><em>深入了解 Swagger 生态：探索 Swagger 工具</em></strong></li></ul>