이전에 Swagger 2.0(구 OAS 2)를 사용하고 있었을 수도 있지만, 이제 OpenAPI Specification(OAS) 3로 업그레이드할 시간입니다. 이 기사에서는 업그레이드 프로세스의 주요 사항과 OAS 3를 사용하여 API 문서를 작성하는 데 필요한 필수 사항을 설명합니다.
이러한 사항 중 일부는 이전 OAS 2(구 Swagger) 문서에도 여전히 적용될 수 있지만, 제가 이전에 이를 충분히 강조하지 않았을 수 있으므로 주목할 가치가 있습니다.
이 기사의 코드 예제는 bookmarks.dev-api의 OAS 3 사양에서 추출되었으며, GitHub의 openapi.yaml 파일에서 찾을 수 있습니다. 결과는 bookmarks.dev/api/docs/에서 확인할 수 있습니다.
다음은 10가지 주요 고려 사항입니다:
1. 사양 문서 읽기
"OpenAPI 3.0의 새로운 내용에 대한 가이드" 기사를 읽어보세요. 이 기사는 OAS의 최신 버전에서 진행된 주요 업데이트 중 일부를 공유하고 OAS 2.0에서 OAS 3.0으로 전환할 때 알아야 할 사항에 대한 자세한 통찰력을 제공합니다. 이 기사는 "OpenAPI 3.0, Swagger의 미래에 대한 의미"라는 1시간 웨비나를 기반으로 작성되었습니다.
2. 변환기 웹 서비스 사용
OpenAPI/Swagger 2.0에서 OpenAPI 3.0으로 변환하는 웹 서비스를 사용하여 Swagger 사양을 OpenAPI 3.0으로 변환하세요.
온라인에서 https://converter.swagger.io/에서 이용할 수 있으며, Docker 이미지로도 사용할 수 있습니다:
docker pull swaggerapi/swagger-converter:v1.0.2
docker run -it -p 8080:8080 --name swagger-converter swaggerapi/swagger-converter:v1.0.2
3. 사양 검증 및 Swagger Editor로 미리보기
Swagger Editor는 웹 브라우저에서 YAML 형식의 Swagger API 사양을 편집하고 문서를 즉시 미리 볼 수 있게 해줍니다.
온라인 또는 npm으로 게시된 버전 또는 Docker 이미지로 사용할 수 있습니다. 자세한 내용은 프로젝트의 README를 참조하세요.
4. Swagger UI로 문서 보여주기
Swagger UI는 Swagger 준수 API에 대한 아름다운 문서를 동적으로 생성하는 HTML, JavaScript 및 CSS 리소스 모음입니다.
예를 들어 bookmarks.dev/api/docs/와 같은 API 경로를 통해 Swagger UI 문서에 직접 접근하여 저처럼 사용할 수 있습니다. app.js에서 가져온 코드 스니펫은 다음과 같습니다:
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
const swaggerDocument = YAML.load('./docs/openapi/openapi.yaml');
app.use('/api/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
nodemon 감시에서 open specification 파일(openapi.yaml)을 포함하면 유용할 수 있으며, ExpressJS 서버를 수동으로 다시 시작하지 않고도 UI를 다시 로드할 수 있습니다.
4.1. 코드 우선 접근 방식을 위한 swagger-jsdoc 사용
또한 주목할 점은 swagger-jsdoc를 사용하여 코드 내 JSDoc 주석을 통해 Swagger를 통합할 수 있다는 것입니다. swagger-jsdoc 프로젝트는 기존의 활성 코드에 "생명력을 불어넣는" 방식으로 문서화하려고 하는 것을 전제로 하며, 다른 Swagger 도구에 공급될 수 있는 사양을 생성합니다.
현재 저는 단일 openapi.yaml 파일에서 문서를 관리하고 있지만, 미래에는 사용하는 것을 고려할 수 있습니다.
5. 태그를 사용하여 작업 그룹화하기
각 API 작업에 태그 목록을 할당하여 Swagger UI와 Swagger Editor가 태그별로 작업을 표시할 수 있도록 편리하게 만들 수 있습니다. Swagger UI에서 정렬을 제어하려면 루트 수준에서 글로벌 태그로 추가해야 합니다. 거기에서 설명 및 외부 문서에 대한 링크도 추가할 수 있습니다.
다음은 제가 API에 사용하는 태그입니다:
yamlCopy code
tags:- name: rootdescription: 루트 엔드포인트를 표시하는 데 사용됨- name: versiondescription: 프로젝트 버전 및 gitSha1에 접근- name: public-bookmarksdescription: 공개 북마크에 접근- name: personal-bookmarksdescription: 개인 북마크에 대한 작업- name: user-datadescription: 사용자 데이터에 대한 작업- name: helperdescription: 헬퍼 엔드포인트/작업
6. 서버로 API 기본 URL 지정하기
OpenAPI 3.0에서는 servers 배열을 사용하여 API의 하나 이상의 기본 URL을 지정합니다. 서버는 OpenAPI 2.0에서 사용된 host, basePath, 및 schemes 키워드를 대체합니다. 각 서버는 URL 및 선택적인 Markdown 형식의 설명을 가집니다.
yamlCopy code
servers:- url: http://localhost:3000/apidescription: 개발용 로컬 서버- url: https://www.bookmarks.dev/apidescription: 메인(생산) 서버
7. 구성 요소로 리소스 정의 및 재사용하기
종종 여러 API 작업이 공통 매개변수를 공유하거나 동일한 응답 구조를 반환합니다. 코드 중복을 피하기 위해 공통 정의를 전역 구성 요소 섹션에 배치하고 $ref를 사용하여 참조할 수 있습니다.
예를 들어 여러 작업에서 북마크 목록이 나타나는 공통 응답을 위해 components > responses 아래에 BookmarkListResponse를 정의합니다:
components:responses:BookmarkListResponse:description: 북마크 목록content:application/json:schema:type: arrayitems:$ref: "#/components/schemas/Bookmark"
그런 다음 get-public-bookmarks와 같은 다양한 작업에서 이를 참조합니다:
yamlCopy code
/public/bookmarks:get:summary: 쿼리 매개변수를 사용하여 공개 북마크 목록 반환tags:- public-bookmarksparameters:- $ref: "#/components/parameters/searchTextQueryParam"- $ref: "#/components/parameters/limitQueryParam"- $ref: "#/components/parameters/locationQueryParam"responses:200:description: OK$ref: "#/components/responses/BookmarkListResponse"
위에서 언급한 locationQueryParam에 주목하세요. 이는 components > parameters에 정의되어 있으며, 위에 표시된 예제를 포함하여 API 사양의 여러 장소에서 참조됩니다.
8. 명확성을 위한 예제 추가하기
매개변수, 속성 및 객체에 예제를 추가하여 웹 서비스의 사양을 더 명확하게 만들 수 있습니다. 예제는 API의 도구와 라이브러리가 읽을 수 있습니다. 예를 들어, 모의 API 도구는 예제 값을 사용하여 모의 요청을 생성할 수 있습니다. 예제 또는 examples 키를 사용하여 객체, 개별 속성 및 작업 매개변수에 대한 예제를 지정할 수 있습니다.
예를 들어 검색 텍스트 매개변수에 대한 복잡한 값을 예제로 가질 수 있습니다:
components:parameters:searchTextQueryParam:name: qin: querydescription: |
검색 쿼리(공백으로 구분된 단어들). 사용 가능한 특별 필터:
* `lang:iso_language_code` - 예: `lang:en` 영어, `lang:es` 스페인어, `lang:de` 독일어 북마크
* `site:site_URL` - 예: [www.codepedia.org](htt
