swagger-ui + heroku-review-apps에서 API 문서를 누구나 볼 수 있고 검토할 수 있는 상태로 만들기

마에오키

Swagger로 쓴 API 문서를 GitHub flow로 유지할 때 어떻게 하면 좋을까라고 생각한 이야기.
Pull Request 시점에서 heroku-review-apps의 미리보기 환경이 자동으로 일어나 swagger-ui 볼 수 있으면, 대부분 검토하기 쉬워질 것 같네요.

그래서,

API를 만드는 사람은 Swagger Editor에서 문서를 작성하고 swagger.yml에 반영합니다

Pull Request에서 리뷰어는 yml이 아니라 HTML API 문서에서 리뷰하고 싶습니다!

정도를 요건으로 생각해 보았다 & 해봤다.

swagger-ui를 최소 구성으로 이동하는 방법?

다양한 Qiita 기사에서 쓰여진 것처럼, swagger-ui는
htps : // 기주 b. 코 m / 슈 게 r- 아피 / 슈 게 r - 우 / b ぉ b / 뭐 r / st /
부하를 완전히 복사하면 Node가 없는 환경에서도 움직인다.

더 말하면, Favicon이 필요하지 않다면, CDN을 이용하는 것으로, index.html만으로 움직일 수 있다.

    <link rel="stylesheet" type="text/css" href="./swagger-ui.css" >

    <script src="./swagger-ui-bundle.js"> </script>
    <script src="./swagger-ui-standalone-preset.js"> </script>

곳을 ↓처럼 다시 쓰면 좋을 뿐이다.

    <link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.17.2/swagger-ui.css" >

    <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.17.2/swagger-ui-bundle.js"> </script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.17.2/swagger-ui-standalone-preset.js"> </script>

heroku-buildpack-static을 사용하여 Heroku에서 호스팅

index.html만으로 동작하므로, heroku-buildpack-node라든지 사용할 필요도 없고, heroku-buildpack-static 로 호스트 할 수 있다.

index.html의 url 다시 쓰기

기본 URL이 https://petstore.swagger.io/v2/swagger.json이므로, 거기는 /swagger.yml
index.html

      // Build a system
      const ui = SwaggerUIBundle({
        url: "https://petstore.swagger.io/v2/swagger.json", //←ここを"/swagger.yml"に書き換える
        dom_id: '#swagger-ui',

파일 배치 및 static.json 준비

swagger.yml
static.json
dist/
  |- index.html

이런 느낌의 디렉토리 구조로, static.json이라는 파일을 이하의 내용으로 준비한다.

static.json

{
  "root": "dist/",
  "routes": {
    "/swagger.yml": "../swagger.yml"
  }
}

dist/를 루트 디렉토리로 하고 있기 때문에, swagger.yml 를 1 계층상에 따르지 않으면 안 되는 것 같다.

우선 배포해 봅시다.

여기까지 하면

$ heroku buildpacks:set https://github.com/heroku/heroku-buildpack-static -a アプリ名
$ git push heroku master

그리고 수동으로 배포하면 swagger-ui 문서를 볼 수 있습니다.

헤더가 방해이므로 지우기

htps : // 홉 x. 어리석은 p. 코m/

에 방법이 쓰여 있었다.

index.html에 쓰여진 JS를 조금 수정하십시오.

// https://github.com/swagger-api/swagger-ui/wiki/FAQ#how-to-hide-topbarにあるように定義
function HideTopbarPlugin() {
  // this plugin overrides the Topbar component to return nothing
  return {
    components: {
      Topbar: function() { return null }
    }
  }
}


SwaggerUIBundle({
  url: "http://petstore.swagger.io/v2/swagger.json",
  dom_id: '#swagger-ui',
  presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIStandalonePreset
  ],
  plugins: [
    SwaggerUIBundle.plugins.DownloadUrl,
    HideTopbarPlugin //←これを追加
  ],

이렇게함으로써

htps : // 기주 b. 코 m / 슈 게 r- 아피 / 슈 게 r 우 / ぃ き / ふ Q # 호와 히데와 p

이런 느낌으로 깨끗이 없어 준다.

heroku-review-apps 설정

근처를 참고로, Heroku의 콘솔로 포치포치 하면 된다.

요약

Pull Request 시점에서 미리보기 환경이 자동으로 일어나 swagger-ui 만지면 역시 많이 검토하기 쉬워질 것 같습니다.

htps : // 코 m / 콘 _ 유 / ms / 6d2c0 꺾어 91d0176 세 b167 # 레 w ぃ 왓 ps % 에 3 % 81 % 네 % 8 % 아 8 % 오 D % %81%99%에3%82%8B 에 이번 시험 내용을 넣어 보았습니다.