如何在GitLab中渲染展示Swagger API文档而非源码？

• 先确认GitLab版本：GitLab 11.0及以上版本才内置Swagger UI渲染功能，旧版本不支持自动切换视图的功能，要么升级GitLab，要么采用替代方案。
• 文件名必须符合规则：GitLab只会自动识别并渲染以下命名的文件：
  • swagger.yaml / swagger.yml
  • swagger.json
  • openapi.yaml / openapi.yml
  • openapi.json
    如果你用了自定义文件名（比如my-api-spec.yaml），GitLab不会触发自动渲染，改成上面的标准名称即可。
• 验证文件格式正确性：你的YAML/JSON文件必须严格符合OpenAPI（Swagger）2.0或3.x规范。可以用Swagger官方编辑器检查语法错误，格式有问题的话GitLab只会显示源码。从SwaggerHub下载时，确保导出的是原始的规范文件，不是HTML、PDF等其他格式。
• 权限与设置：不需要额外开启GitLab的特殊开关，只要你有该文件的查看权限，且满足上述版本、文件名、格式要求，打开文件时顶部就会出现切换按钮。

如果以上方法都无法解决，可以用GitLab Pages部署独立的Swagger UI：下载Swagger UI的静态资源，将你的API规范文件放入对应目录，配置index.html指向该文件，提交到仓库后启用GitLab Pages，就能通过Pages地址访问渲染好的文档。

内容的提问来源于stack exchange，提问作者diego9999