아티팩트는 여기입니다.
htps : // 슈게 루 rl. 의 w. sh/

Swagger

REST API를 사용하는 프로젝트에서 서버 측과 프런트 엔드에서 합의를 할 때 API 설계서가 있으면 편리합니다.
그 API의 설계서로서는 Swagger가 매우 편리합니다.

OpenAPI (Swagger) 초입문 - Qiita

Swagger는 SwaggerHub라는 서비스 위에서 편집, 확인, 공유할 수 있지만, 설계서가 되는 구성 파일의 Swagger YAML가 프로젝트의 리포지토리로부터 빠져 버립니다.
그래서 Swagger YAML을 프로젝트 리포지토리에 포함시키면서 API 설계 확인 화면을 공유할 수 있도록 했습니다.

Swagger?

이름
역할


Swagger
REST API를 설계하는 메커니즘.

Open API
Swagger를 바탕으로 표준화된 구조. Open API3.0으로 책정.

Swagger Hub
Swagger를 편리하게 팀에서 사용하기 위한 서비스. Swagger는 Git과 GitHub 같은 관계.

Swagger Editor
Swagger를 편집하는 편리한 편집기 (브라우저에서 작동)

Swagger UI
Swagger 파일 (YAML, JSON)을로드하고 표시하는 파일 이번에는 이것이

Swagger UI

Swagger에서 공유하기 위해 Swagger UI이 있습니다.


최종적으로는 이 Swagger UI의 출력을 확인해 갑니다.

손을 넣은 것

Swaggere UI에서는 URL을 입력하여 Yaml과 JSON 파일을로드하여 출력합니다.
Swagger UI 공식에 있는 URL을 로드하는 부분은 아래와 같습니다.

index.html

   window.onload = function() {
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        url: "https://petstore.swagger.io/v2/swagger.json",
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })

Original

여기 SwaggerUIBundle()에 전달 된 url를 URL의 쿼리 매개 변수 (GET에서 취할 수있는 인수)로받을 수 있습니다.

     function get_url() {
        // @see https://stackoverflow.com/questions/35914069/how-can-i-get-query-parameters-from-a-url-in-vue-js
        let uri = window.location.href.split('?');
        if (uri.length === 2) {
          let vars = uri[1].split('&');
          let getVars = {};
          let tmp = '';
          vars.forEach(function (v) {
            tmp = v.split('=');
            if (tmp.length === 2)
              getVars[tmp[0]] = tmp[1];
          });
          return getVars.url;
        }
      }

Swagger UI 상단에는 URL을 입력할 수 있는 URL 입력 양식이 있습니다.



여기를 쿼리 매개 변수로 받은 url 내용으로 채울 수 있습니다.

      function set_url() {
        const button = document.getElementsByClassName("download-url-button")[0];
        const input = document.getElementsByClassName("download-url-input")[0];
        button.addEventListener("click", function() {
          window.location.search = 'url=' + encodeURIComponent(input.value);
        } , false);
      }

배포

배포는 Now.sh를 사용했습니다. 굉장히 편리하네요!

Now로 클라우드 복잡성을 풀어 보세요. 지금 - Qiita

사용법

GitHub에서 Yaml 파일을 관리하고 파일에 대한 직접 링크를 "Raw"로 가져옵니다.



예를 들어 다음과 같은 URL입니다.

https://raw.githubusercontent.com/swagger-api/swagger-samples/master/java/inflector-dropwizard/src/main/swagger/swagger.yaml

이것을 Swagger URL의 URL에 입력하면 URL이 인수로 전달됩니다.

https://swagger-url.now.sh/?url=https%3A%2F%2Fraw.githubusercontent.com%2Fswagger-api%2Fswagger-samples%2Fmaster%2Fjava%2Finflector-dropwizard%2Fsrc%2Fmain%2Fswagger%2Fswagger.yaml

그리고는 이 URL을 팀의 Slack등에서 공유할 수 있습니다. 편리!

참고 정보

Swagger의 개요를 정리해 보았다. - Qiita

Swagger의 기법 요약 - Qiita