diff --git a/keyword/chapter08/keyword.md b/keyword/chapter08/keyword.md new file mode 100644 index 0000000..c51aab9 --- /dev/null +++ b/keyword/chapter08/keyword.md @@ -0,0 +1,221 @@ +- Swagger + - RESTful API를 설계, 빌드, 문서화 및 사용하는 데 도움이 되는 Open API 사양을 중심으로 구축된 오픈 소스 도구 + - API 개발자가 아닌 제 3자가 편리하게 API를 호출해보고 테스트를 할 수 있음. + - 잘못하면 코드와 로직을 비롯한 내부 정보가 빠져나갈 수도 있으니 외부에 노출되지 않는 환경에서 사용해야 한다. + - 코드에 주석을 채워 넣어서 API 설명을 정의해줄 수 있다. + + ```jsx + export const handleUserSignUp = async (req, res, next) => { + /* + #swagger.summary = '회원 가입 API'; + #swagger.requestBody = { + required: true, + content: { + "application/json": { + schema: { + type: "object", + properties: { + email: { type: "string" }, + name: { type: "string" }, + gender: { type: "string" }, + birth: { type: "string", format: "date" }, + address: { type: "string" }, + detailAddress: { type: "string" }, + phoneNumber: { type: "string" }, + preferences: { type: "array", items: { type: "number" } } + } + } + } + } + }; + #swagger.responses[200] = { + description: "회원 가입 성공 응답", + content: { + "application/json": { + schema: { + type: "object", + properties: { + resultType: { type: "string", example: "SUCCESS" }, + error: { type: "object", nullable: true, example: null }, + success: { + type: "object", + properties: { + email: { type: "string" }, + name: { type: "string" }, + preferCategory: { type: "array", items: { type: "string" } } + } + } + } + } + } + } + }; + #swagger.responses[400] = { + description: "회원 가입 실패 응답", + content: { + "application/json": { + schema: { + type: "object", + properties: { + resultType: { type: "string", example: "FAIL" }, + error: { + type: "object", + properties: { + errorCode: { type: "string", example: "U001" }, + reason: { type: "string" }, + data: { type: "object" } + } + }, + success: { type: "object", nullable: true, example: null } + } + } + } + } + }; + */ + res.success(...); + }; + ``` + + - 중복되는 schema는 한 곳에서 관리하고 주석에서 $ref를 통해 참조만 할 수 있게 할 수도 있음. + + ```jsx + const doc = { + ... + components: { + schemas: { + someSchema: { + $name: 'John Doe', + $age: 29, + about: '' + }, + ... + } + } + }; + + //$ref로 호출하기 + app.get('/path', (req, res) => { + ... + /* #swagger.requestBody = { + required: true, + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/someSchema" + } + } + } + } + */ + ... + /* #swagger.responses[200] = { + description: "Some description...", + content: { + "application/json": { + schema:{ + $ref: "#/components/schemas/someSchema" + } + } + } + } + */ + ... + + }) + ``` + +- OpenAPI + - Open API - 개방된 API. 누구나 사용할 수 있도록 API의 endpoint가 공개되어 있는 API. + - OpenAPI - OpenAPI Specification. RESTful API를 정의된 규칙에 맞게 API의 spec을 json이나 yaml로 표현하는 방식. 소스코드나 별도의 문서 없이 API의 서비스를 이해할 수 있다. + - Swagger vs OpenAPI - 옛날에는 OpenAPI 2.0을 swagger 2.0이라고 했었음. 그러다 OpenAPI로 완전히 이름이 변경되었고, 지금 swagger는 OpenAPI를 쓰기 위한 도구라는 의미로 쓰임. +- OpenAPI 버전 별 특징 및 주요 차이점 + - Swagger를 OpenAPI에 기부하면서 OpenAPI 3.0 출시. 2.0에 비해서 구조가 단순해지고 재상용성이 증가될 수 있도록 개발됨. + + ![image.png](https://prod-files-secure.s3.us-west-2.amazonaws.com/d32beb2d-cafa-4d99-b608-dd96a7f92d4d/e4da28c1-237b-4087-8b3d-f70c5317ad3a/image.png) + + - 2.0에서는 API Endpoint URL을 3가지(host, basePath, schemes)로 정의함. 3.0부터는 멀티 URL을 지원함. + + ```jsx + "host": "petstore.swagger.io", + "basePath": "/v1", + "schemes": [ + "http" + ] + ``` + + ```jsx + "servers": [ + { + "url": "https://{username}.gigantic-server.com:{port}/{basePath}", + "description": "The production API server", + "variables": { + "username": { + "default": "demo", + "description": "this value is assigned by the service provider, in this example `gigantic-server.com`" + }, + "port": { + "enum": [ + "8443", + "443" + ], + "default": "8443" + }, + "basePath": { + "default": "v2" + } + } + } + ] + ``` + + - Component 기능 - 2.0에서는 중복되는 것이 있어도 일일이 다 적어줘야 했다. 3.0 부터는 component 기능으로 참조할 수 있게 만들어놔서 중복성이 줄어들고 유지보수가 편해졌다. +- OpenAPI Component + + ```jsx + const doc = { + ... + components: { + schemas: { + someSchema: { + $name: 'John Doe', + $age: 29, + about: '' + }, + ... + } + } + }; + + //$ref로 호출하기 + app.get('/path', (req, res) => { + ... + /* #swagger.requestBody = { + required: true, + content: { + "application/json": { + schema: { + $ref: "#/components/schemas/someSchema" + } + } + } + } + */ + ... + /* #swagger.responses[200] = { + description: "Some description...", + content: { + "application/json": { + schema:{ + $ref: "#/components/schemas/someSchema" + } + } + } + } + */ + ... + + }) + ``` + + - Component를 통해 중복되는 scheme은 따로 저장해 놓아서 관리하고 $ref로 호출해서 사용할 수 있다. schemas, parameters, responses, examples, security schemes, links, request bodies, headers, callbacks를 포함한다. \ No newline at end of file diff --git a/mission/chapter08/1.PNG b/mission/chapter08/1.PNG new file mode 100644 index 0000000..9daba7a Binary files /dev/null and b/mission/chapter08/1.PNG differ diff --git a/mission/chapter08/2.PNG b/mission/chapter08/2.PNG new file mode 100644 index 0000000..38fcab4 Binary files /dev/null and b/mission/chapter08/2.PNG differ diff --git a/mission/chapter08/3.PNG b/mission/chapter08/3.PNG new file mode 100644 index 0000000..8664ad8 Binary files /dev/null and b/mission/chapter08/3.PNG differ diff --git a/mission/chapter08/4.png b/mission/chapter08/4.png new file mode 100644 index 0000000..6cc86b4 Binary files /dev/null and b/mission/chapter08/4.png differ diff --git a/mission/chapter08/5.png b/mission/chapter08/5.png new file mode 100644 index 0000000..aff47d1 Binary files /dev/null and b/mission/chapter08/5.png differ diff --git a/mission/chapter08/6.png b/mission/chapter08/6.png new file mode 100644 index 0000000..737d280 Binary files /dev/null and b/mission/chapter08/6.png differ diff --git a/mission/chapter08/7.png b/mission/chapter08/7.png new file mode 100644 index 0000000..bb6c711 Binary files /dev/null and b/mission/chapter08/7.png differ diff --git a/mission/chapter08/8.png b/mission/chapter08/8.png new file mode 100644 index 0000000..b272290 Binary files /dev/null and b/mission/chapter08/8.png differ diff --git a/mission/chapter08/9.png b/mission/chapter08/9.png new file mode 100644 index 0000000..e012100 Binary files /dev/null and b/mission/chapter08/9.png differ diff --git a/mission/chapter08/mission.md b/mission/chapter08/mission.md new file mode 100644 index 0000000..139bdd4 --- /dev/null +++ b/mission/chapter08/mission.md @@ -0,0 +1,36 @@ +- **미션 기록** + + # Swagger 주석 + + - Swagger 주석으로 만들기 + + ![1.PNG](./1.png) + + - 에러처리를 해야 하는 경우 (status code가 다를 때) + + ![2.PNG](./2.png) + + ![3.PNG](./3.png) + + - 목록형 자료형을 받아올 때 (type: array, item: object) + + ![image.png](./4.png) + + + # 실행 결과 + + - 실제 swagger 페이지 모습 + + ![image.png](./5.png) + + - API 상세 모습 + + ![image.png](./6.png) + + ![image.png](./7.png) + + - swagger에서 API 테스트 해보기 + + ![image.png](./8.png) + + ![image.png](./9.png) \ No newline at end of file