From 0485583c892e994c7ea7300a8e0fba5d0e57779b Mon Sep 17 00:00:00 2001 From: tae0y Date: Sun, 18 Aug 2024 18:53:13 +0900 Subject: [PATCH 1/5] Add spectral rules #20 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit related to #20, #21 필수 필드를 지정하고, 해당 필드가 없을 경우 에러를 발생시키도록 수정 --- .spectral.yaml | 115 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 .spectral.yaml diff --git a/.spectral.yaml b/.spectral.yaml new file mode 100644 index 00000000..2c321323 --- /dev/null +++ b/.spectral.yaml @@ -0,0 +1,115 @@ +extends: + - spectral:oas +rules: + # API 버전 규칙 : v로 시작하고 숫자와 점으로 이루어져야 함 + api-version-convention: + description: API version should follow the convention + given: $.info.version + severity: error + then: + function: pattern + functionOptions: + match: "^v[0-9\\.]+$" + message: API version should follow the convention v1, v2.1, v3.0.1, etc. + + # 모든 엔드포인트는 tags를 포함해야 함 + operation-tags-convention: + description: All Operation should include tags + given: $.paths[*][*] + severity: error + then: + - field: tags + function: truthy + message: Tags are required + + # 모든 엔드포인트는 operationId를 포함해야 함 (.WithName 으로 지정) + operation-operationid-convention: + description: All Operation should include operationId + given: $.paths[*][*] + severity: error + then: + - field: operationId + function: truthy + message: OperationId is required + + # 모든 엔드포인트는 summary와 description을 포함해야 함 + operation-summary-description-convention: + description: All Operation should include summary and description + given: $.paths[*][*] + severity: error + then: + - field: 'summary' + function: truthy + message: Summary is required + - field: 'description' + function: truthy + message: Description is required + + # Post 요청의 경우 requestbody가 정의되어 있어야함 + operation-request-convention: + description: Post Operation should include request body + given: $.paths[*].post + severity: error + then: + - field: requestBody + function: truthy + message: Request body is required + + # Get 요청의 경우 parameters가 정의되어 있어야함 + operation-parameters-convention: + description: Get Operation might include parameters + given: $.paths[*].get + severity: warn # 파라미터가 없는 Get 요청에 대응 + then: + - field: parameters + function: truthy + message: Parameters are required + + # 응답이 정의되어 있어야함 + operation-response-convention: + description: All Operation should include response + given: $.paths[*][*] + severity: error + then: + - field: responses + function: truthy + message: Responses are required + + # 응답 코드 규칙 : 200, 401, 500 응답 코드가 있어야 함 + operation-responsecode-convention: + description: All Operation response should include 200, 401, 500 with description, content + given: $.paths[*][*].responses + severity: error + then: + - field: '200' + function: truthy + message: Response 200 is required + - field: '401' + function: truthy + message: Response 401 is required + - field: '500' + function: truthy + message: Response 500 is required + + # 각 응답 코드는 descriptioin과 content를 포함해야함 + operation-responsedetail-convention: + description: All Operation response should include description, content + given: $.paths[*][*].responses[*] + severity: error + then: + - field: 'description' + function: truthy + message: Description is required + - field: 'content' + function: truthy + message: Content is required + + # 각 응답 코드는 descriptioin과 content를 포함해야하는데, 401은 content가 없어도 됨 + operation-responsedetail-convention: + description: All Operation response should include description, content + given: $.paths[*][*].responses[*] + severity: off + then: + - field: 'content' + function: truthy + message: Content is not required when response code is 401 \ No newline at end of file From 7214b5b4077ce58803ba07b772740fd192d196cd Mon Sep 17 00:00:00 2001 From: tae0y Date: Sun, 18 Aug 2024 18:53:13 +0900 Subject: [PATCH 2/5] Add comment in spectral rules --- .spectral.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.spectral.yaml b/.spectral.yaml index 2c321323..3f3dcea5 100644 --- a/.spectral.yaml +++ b/.spectral.yaml @@ -1,3 +1,4 @@ +# Source: https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules extends: - spectral:oas rules: From 0e9edfd581a287e261cfa62429685b88d9eb32d8 Mon Sep 17 00:00:00 2001 From: tae0y Date: Sun, 18 Aug 2024 18:53:13 +0900 Subject: [PATCH 3/5] =?UTF-8?q?Edit=20spectral=20rules=20-=20response=20?= =?UTF-8?q?=ED=95=98=EC=9C=84=20responsecode=EB=93=A4=EC=9D=80=20content?= =?UTF-8?q?=EB=A5=BC=20=ED=8F=AC=ED=95=A8=20-=20=EB=8B=A4=EB=A7=8C,=20401?= =?UTF-8?q?=20=EC=BD=94=EB=93=9C=EB=8A=94=20content=EB=A5=BC=20=ED=8F=AC?= =?UTF-8?q?=ED=95=A8=ED=95=98=EC=A7=80=20=EC=95=8A=EC=95=84=EB=8F=84=20?= =?UTF-8?q?=EB=90=98=EA=B2=8C=EB=81=94=20=EC=88=98=EC=A0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .spectral.yaml | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/.spectral.yaml b/.spectral.yaml index 3f3dcea5..b47b43ef 100644 --- a/.spectral.yaml +++ b/.spectral.yaml @@ -78,7 +78,7 @@ rules: # 응답 코드 규칙 : 200, 401, 500 응답 코드가 있어야 함 operation-responsecode-convention: - description: All Operation response should include 200, 401, 500 with description, content + description: All Operation response should include 200, 401, 500 given: $.paths[*][*].responses severity: error then: @@ -92,25 +92,22 @@ rules: function: truthy message: Response 500 is required - # 각 응답 코드는 descriptioin과 content를 포함해야함 - operation-responsedetail-convention: - description: All Operation response should include description, content + # 모든 응답 코드는 descriptioin을 포함해야함 + operation-responsedetail-description-convention: + description: All Operation response should include description given: $.paths[*][*].responses[*] severity: error then: - field: 'description' function: truthy message: Description is required - - field: 'content' - function: truthy - message: Content is required - - # 각 응답 코드는 descriptioin과 content를 포함해야하는데, 401은 content가 없어도 됨 - operation-responsedetail-convention: - description: All Operation response should include description, content - given: $.paths[*][*].responses[*] - severity: off + + # 401을 제외한 모든 응답 코드는 content를 포함해야함 + operation-responsedetail-content-convention: + description: All Operation response might include content, except 401 + given: $.paths[*][*].responses[?(@property != '401')] + severity: error then: - field: 'content' function: truthy - message: Content is not required when response code is 401 \ No newline at end of file + message: Content is required \ No newline at end of file From cb5d9d459fa6590cce59c4c558a0babcc17a1db4 Mon Sep 17 00:00:00 2001 From: tae0y Date: Sun, 18 Aug 2024 19:30:05 +0900 Subject: [PATCH 4/5] =?UTF-8?q?Edit=20spectral=20rules=20-=20path=20parame?= =?UTF-8?q?ters=20=EC=BB=A4=EC=8A=A4=ED=85=80=20=EA=B2=80=EC=82=AC?= =?UTF-8?q?=EA=B7=9C=EC=B9=99=20=EC=82=AD=EC=A0=9C=20-=20=EB=82=B4?= =?UTF-8?q?=EC=9E=A5=EB=90=9C=20spectral(path-params)=EB=A5=BC=20=EB=8C=80?= =?UTF-8?q?=EC=8B=A0=20=EC=82=AC=EC=9A=A9=ED=95=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .spectral.yaml | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/.spectral.yaml b/.spectral.yaml index b47b43ef..ede9d180 100644 --- a/.spectral.yaml +++ b/.spectral.yaml @@ -57,15 +57,8 @@ rules: message: Request body is required # Get 요청의 경우 parameters가 정의되어 있어야함 - operation-parameters-convention: - description: Get Operation might include parameters - given: $.paths[*].get - severity: warn # 파라미터가 없는 Get 요청에 대응 - then: - - field: parameters - function: truthy - message: Parameters are required - + # 규칙관리를 위해 각주만 유지, spectral(path-params)에서 이미 검사중임 + # 응답이 정의되어 있어야함 operation-response-convention: description: All Operation should include response From f9791d4d9a33e1b4fdc85ef532a77e9b7d0dec05 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=B0=95=ED=83=9C=EC=98=81?= Date: Mon, 19 Aug 2024 12:31:17 +0900 Subject: [PATCH 5/5] Edit .spectral.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 불필요한 규칙 삭제 - Post RequesstBody는 암시적으로 생성됨, 규칙제거 - Get Parameters는 spectral 내장규칙사용, 불필요 각주제거 - responsecode별 description은 암시적으로 생성됨, 규칙제거 --- .spectral.yaml | 25 +------------------------ 1 file changed, 1 insertion(+), 24 deletions(-) diff --git a/.spectral.yaml b/.spectral.yaml index ede9d180..c69bf5d4 100644 --- a/.spectral.yaml +++ b/.spectral.yaml @@ -45,19 +45,6 @@ rules: - field: 'description' function: truthy message: Description is required - - # Post 요청의 경우 requestbody가 정의되어 있어야함 - operation-request-convention: - description: Post Operation should include request body - given: $.paths[*].post - severity: error - then: - - field: requestBody - function: truthy - message: Request body is required - - # Get 요청의 경우 parameters가 정의되어 있어야함 - # 규칙관리를 위해 각주만 유지, spectral(path-params)에서 이미 검사중임 # 응답이 정의되어 있어야함 operation-response-convention: @@ -85,16 +72,6 @@ rules: function: truthy message: Response 500 is required - # 모든 응답 코드는 descriptioin을 포함해야함 - operation-responsedetail-description-convention: - description: All Operation response should include description - given: $.paths[*][*].responses[*] - severity: error - then: - - field: 'description' - function: truthy - message: Description is required - # 401을 제외한 모든 응답 코드는 content를 포함해야함 operation-responsedetail-content-convention: description: All Operation response might include content, except 401 @@ -103,4 +80,4 @@ rules: then: - field: 'content' function: truthy - message: Content is required \ No newline at end of file + message: Content is required