GitLab は OpenAPI (Swagger) の YAML/JSON ファイルビューアが組み込まれている

bookwor.ms

@KitaitiMakoto これ https://t.co/UGuzRf5ra0 気になったので試してみました。 GitLab に Swagger YAML ファイル置くだけでうまいこと表示してくれますね。 https://t.co/AdHbGlAteL
ここで入ったのかな？ https://t.co/yPjDxjmuuZ

— kyanny (@kyanny) August 5, 2020

二年前に提案されて、七ヶ月前にマージされ、 GitLab 12.6 のリリースに含まれたようだ。

• Issue
• Merge Request
• 12.6 Release ChangeLog
  • Documentation

ファイル名が (swagger|openapi).(yml|yaml|json) みたいなパターンにマッチすれば OpenAPI 3 ドキュメントとしてレンダリングしてくれるようだ。

実装は、 swagger-ui-dist の SwaggerUIBundle に YAML/JSON ファイルの URL を食わせているだけ。

実際に GitLab に置いてみたら本当にちゃんとレンダリングされた。

• swagger.yml · master · Kensuke Nagae / test swagger yml · GitLab

同じファイルを GitHub に置いてもレンダリングしてくれない。

• test-swagger-yml/swagger.yml at master · kyanny/test-swagger-yml · GitHub

GitLab CI で Swagger/OpenAPI の YAML/JSON をビルドして HTML を Pages に公開する方法は検索するといくつか出てきた。同じことは GitHub Actions + GitHub Pages でもできるだろう。

GitLab の組み込みビューアは認証が必要な領域内で完結する点が優れている。外部に公開したくない API ドキュメントを手軽にホストできる。