개요

swaggerhub를 사용해 API 설계하면서 구현해, 공개까지가 매우 편리했기 때문에, 조금은 느슨한 점 등 잊지 않게 일대로 기재해 둡니다.

사용한 도구는 swaggerhub와 swagger inspector의 두 가지입니다. swaggerhub에서 yaml 형식 또는 json 형식으로 API 설계가 가능합니다. swagger inspector는 API를 테스트하는 데 사용되었습니다. swaggerhub에서도 테스트는 가능하지만, 보다 상세하게 파라미터를 조작하거나 로그가 기록되므로 여러 번 비슷한 쿼리를 보내는 경우 등에는 swagger inspector가 편리합니다.

htps : // 슈게 r. 이오 / 토오 ls / 슈 게 r 후 b /


htps : // 인 spec 및 r. 슈게 r. 이오/부이 l로 r

OpenAPI

swaggerhub에서는 swagger2.0과 swagger3.0(OpenAPI 3.0)으로 작성할 수 있으며, 새로 만들려면 swagger3.0을 선택합시다. 설명의 방법이 조금 다른 것 같습니다.

API 사양서 작성한다면 swagger v2.0에서 v3.0으로 변경할 때의 포인트
htps : // 코 m / 슈니치_코 m / ms / 63114f8d67 베바 14bfd

github와 협력

swaggerhub에서 편집 버튼을 누르면 자동으로 github로 푸시 할 수 있습니다. 편집 로그로서 나중에 확인하는 등 편리한 것이 많기 때문에 제휴하는 것을 추천합니다.

github에서 먼저 저장소를 만들고 https://github.com/settings/tokens의 Personal access tokens에서 accesstoken을 만듭니다. (작성시, repo 관계의 권한은 유효하게 해 둡니다.)

그런 다음 swaggerhub에서 오른쪽 상단의 설정 버튼을 클릭 → "Edit Github Push"를 클릭하고 access token 및 리포지토리 등의 항목을 입력하고 "SAVE"를 누릅니다.


그 후, 파일을 편집 후 상단의 "SAVE"버튼을 누르면 자동으로 푸시됩니다!

components를 사용합시다.

components 기능을 돌릴 수 있습니다. components를 사용하면 기술량이 줄어들고, API의 Schema로서 등록되므로 API 이용자에 의해 알기 쉽게 표기됩니다.

api.yaml

components:
  schemas:
    Messages:
      type: object
      properties:
        messages:
          type: array
          items:
            type: string
          example:
            - "success"

allOf와 Oneof

allOf와 Oneof라고 하는 기술의 방법이 있어, 사용하면 매우 편리합니다. components를 작성하고, 그것을 맞추거나, 선택사항을 표기할 때에 사용합니다.

allOf는 스키마를 정렬할 때 사용합니다. 아래의 예는 Messages의 component와 Webhooks의 component를 맞춘다는 의미입니다.

allOf:
    - $ref: '#/components/schemas/Messages'
    - $ref: '#/components/schemas/Webhooks'

oneOf는 어느 쪽인가가 적용된다는 의미로, 선택사항을 나타내고 싶을 때에 편리합니다.

oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'

공식에 자세한 설명이 실려 있습니다!
htps : // 슈게 r. 이오 / 드 cs / s 페시 후 카치 온 / Data-mo ls / Oneo f-Anif-A-F-t /

API 공개

API를 공개할 때는, 자 서비스에 그 API 문서를 올리거나 한다고 생각합니다만, swaggerhub로 자동으로 문서를 작성되어 그대로 자 ​​서비스의 홈 페이지에 html을 붙일 수가 있습니다. 또한 오른쪽 상단의 "View Documentation"을 클릭하면 좋은 느낌의 API 문서 페이지를 볼 수 있습니다.


「try it out」의 기능을 사용하면 그 API의 테스트 송신을 할 수도 있습니다!