swagger ui在github pages的使用以及简易的多

现在大多数api开发都使用swagger，而swagger 文档想要被发布出去，则需要一台服务器在那里一直运行。
但是运行服务器又会带来维护的成本，那么有没有办法不用维护服务器而且可以方便发布api文档的呢？

github pages是一个不错的选择。配置github pages使用swgger的方法比较简单，只需要在项目的setting中找到github pages，在source目录下选择master branch/docs folder选项。

image.png

完成设置后，在你的项目下面创建一个docs目录，swagger docs中的文件可以从这里下载：https://github.com/beego/swagger，下载好之后打开index.html文件，修改url字段，改为你要使用的swagger文件的路径名，之后提交到github 仓库，等待大约20分钟左右，就可以通过访问pages的界面来访问swagger ui的界面了。

image.png

随之而来还有一个问题，如果有多个版本的api都要发布该怎么办呢？本文介绍一个简单的方法，那就是通过github pages的url带query parameters的方法来完成版本的切换。直接上干货：

window.onload = function() {
      // Begin Swagger UI call region
      var url = window.location.search.match(/version=([^&]+)/);
      if (url && url.length > 1) {
        url = "swagger_"+decodeURIComponent(url[1])+".yaml";    
      }else{
          url = "swagger_v1.2.0.yaml"
      }
      
      const ui = SwaggerUIBundle({
        url: url,
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
      // End Swagger UI call region

      window.ui = ui

修改index.html文件，增加对url的query parameters处理的逻辑（这里增加一个version的parameters，那么访问github pages的方式可以是https://github.com/pages/project/?version=v1.0.0），同时将version增加到swagger文档的命名中，这样就可以简单的通过version的切换来完成api 版本的切换。更深一层，可以新建一个index.html，完成版本链接的对应。

还有一种方法是修改swagger ui的原始代码，直接在界面上版本相关内容并完成route，但是这个实现比较复杂，有兴趣的话可以自己尝试。