Swagger (OpenAPI) 시작

안녕하세요.

처음으로 SPA를 이치에서 만들고 있습니다. 이전의 사건도 SPA였지만, 입사한 시점에서 API의 대부분은 구현되고 있었습니다.

그러나 이번은 새로운 안건입니다. 백엔드의 구현을 다른 사람이 하고 있기 때문에, 지금은 스프레드 시트로 API를 대충 결정해 주고 받고 있습니다만, Swagger도 만져 보고 싶다.

라는 것으로, Swagger를 만지기 시작한 초보자의 초보자에 의한 초보자를 위한 기사입니다.

Swagger (OpenAPI)?

편평하게 말하면, API의 사양을 문서로 하기 위한 사양입니다. 자세한 설명은 누군가의 기사에게 양보합니다.

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

사양서를 작성하기 시작합시다.

API 사양은 YAML 또는 JSON으로 작성합니다.

최소 구성은 다음과 같습니다.

swagger: "2.0"
info:
  title: "Hello World"
  version: "1.0.0"
paths:
  /:
    get:
      responses:
        200:
          description: "success"

Swagger Editor의 예라면 paths가 너무 많아서 잘 모르겠지만, 일단 "어디에 액세스하면 어떤 상태가 돌아오는지"를 씁니다. 처음 한 걸음입니다. 앞으로도 paths에 path를 추가하는 경우는 responses에서 쓰기 시작하면 좋을 것입니다.

미리보기에서 살펴보면 다음과 같이 보입니다.

미리보기에서 요청을 보내자.

생성된 문서에서 "Try it out"버튼을 클릭하면 매개변수 입력 양식 또는 "Execute"버튼이 표시되어 정의한 API에 요청을 제출할 수 있습니다.

기본 대상은 상대 경로의/입니다. 즉, Swagger Editor에서 열려 있으면 https://editor.swagger.io/에서 이대로는 Editor에서 두드려도 자신의 서버로 보낼 수 없습니다. 대상을 설정합시다.

대상 설정은 host와 basePath입니다. 자신의 환경에 맞게 설정하십시오.

실제로 설정하면 다음과 같습니다.

swagger: "2.0"
info:
  title: "Hello World"
  version: "1.0.0"
host: "hoge.example.dev"
basePath: "/api/v1"
paths:
  /:
    get:
      responses:
        200:
          description: "success"

사양서를 확장하자.

이 기사는 여기까지입니다.

다음은 path의 summary나 parameters, responses.schema를 추기해 가게 됩니다. 즉, path 의 개요와, 입력, 출력의 상세한 정의입니다.

그 외에도 info.description(자세한 설명)이나 tags, definitions등의 사양이 산만큼 있습니다만, 그들은 옵션입니다. 어쨌든 처음에는 각각의 패스와 입출력을 써 가서, 중복을 tags나 definitions에 옮겨 가게 될 것입니다.

그럼.

공식 사이트 : htps : // 슈게 r. 이오/

이 기사는 내 개인 블로그의 전재입니다.