[API Document] Swagger

Seokr 2018. 12. 30. 17:07

2018. 12. 30. 17:07

[API Document] Swagger

Swagger란?

- Web API 문서화 도구
- API들이 가지는 명세(Spec)을 관리하기 위한 프로젝트

Swagger의 기능

1) API Design
2) API Development
3) API Documentation
4) API Testing
5) API Mocking and Virtualization
6) API Governance
7) API Monitoring
8) OpenAPI & Swagger

Web API를 만들지 않고 명세화하기 (Guide)

Create new API (Link)
1. 왼쪽 사이드 바에서 Create New API를 누르고 선택

2. API 정보를 입력해야 하는 대화 상자가 표시됨

선택 사항	설명
OpenAPI Version	- API 형식을 선택, OpenAPI 2.0 또는 3.0
Template	- Petstore 또는 IOT(Internet of Things)등등 해당 샘플 API를 선택 - 빈 API로 시작하려면 None을 선택
Name	- API 이름은 고유한 ID로 swaggerhub 경로에 포함되어 있다 - https://app.swaggerhub.com/api/{owner}/petstore/1.0 - Name 규칙 1. 3 to 60 character long 2. allowed characters: A..Z a..z 0..9 - _ . 3. must start and end with a letter or digit * 주의 API name은 case-sensitive하므로 petstore와 PetStore는 다르게 인식한다.
Owner	- personal 또는 organization계정에 API를 만들 것인지 선택 - API 소유자는 Swagger의 API 경로에 속한다. https://app.swaggerhub.com/api/owner/api-name/1.0 - ororganization 소유의 API는 personal이 아닌 ororganization의 범위 안에서 제한된다. - organization 소유자는 organization에서 API를 생성할 수 있다. - Allow Designers to Create APIs under the Organization 옵션을 갖고 구성된 organization에서 Designer role을 갖고 있는 멤버는 "create" 권한을 가질 수 있다.
Project	- organization 이 Owner로 선택된 경우, API를 추가할 프로젝트를 선택할 수 있다. - 목록에는 사용자가 사용할 수 있는 기존 프로젝트가 포함되어 있다.
Visibility	- API를 공개할 지 비공개할 지 선택 - Public API는 SwaggerHub의 계정이 없는 사람들도 볼 수 있다. - Private API는 사용자와, collaborators로 등록한 사람들만 볼 수 있다.
Auto Mock API	- https://virtserver.swaggerhub.com/{owner}/{api}/{version}에 새 mock용 API를 만들 수 있다. - 위 방식으로 API를 설계할 때 테스트할 수 있으며, API 기능이 구현될 때까지 기다릴 필요 없이 개발자가 클라이언트 어플리케이션 작업을 시작할 수 있다. - SwaggerHub은 새로운 API를 위한 API Auto Mocking integration을 만들어 API를 저장할 때마다 자동으로 Mock을 업데이트한다.
Version	- 템플릿 없는 빈 API일 경우 작성 - API 버전
Title	- 템플릿 없는 빈 API일 경우 작성 - 대화형 API 문서에 표시될 API 제목
Description	- API의 용도에 대한 개요 - 설명은 API 정의에 포함되며 SwaggerHub의 검색 결과에도 표시된다. -