https://docs.discourse.org/openapi.json에서 OpenAPI / Swagger 검증

https://docs.discourse.org/openapi.json 의 Swagger 정의가 유효하지 않은 것 같습니다.

재현 시나리오:

몇 초 후, 142개의 검증 오류가 발생합니다.

첨부할 수는 없지만, 다음과 유사합니다:

Structural error at paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.name.description
should be string
Jump to line 184
Structural error at paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.color.description
should be string
Jump to line 187
Structural error at paths./categories.json.post.responses.200.content.application/json.schema.properties.category.properties.text_color.description
should be string
Jump to line 190
... more ...

대안(유효한) Swagger 정의가 제공됩니까?

제안된 패치

아래는 지금까지 제안된 패치입니다.

요약
diff --git "a/discourse-swagger-original.json" "b/discourse-swagger.json"
index f9267f5d0..dcebe3fd8 100644
--- "a/discourse-swagger-original.json"
+++ "b/discourse-swagger.json"
@@ -578,8 +578,8 @@
                         },
                         "available_groups": {
                           "type": "array",
-                          "uniqueItems": null,
-                          "minItems": null,
+                          "uniqueItems": false,
+                          "minItems": 0,
                           "items": {
                             "type": "object"
                           }
@@ -1196,8 +1196,8 @@
                     },
                     "actions_summary": {
                       "type": "array",
-                      "uniqueItems": null,
-                      "minItems": null,
+                      "uniqueItems": false,
+                      "minItems": 0,
                       "items": {
                         "type": "object"
                       }
@@ -1788,8 +1788,8 @@
                               },
                               "actions_summary": {
                                 "type": "array",
-                                "uniqueItems": null,
-                                "minItems": null,
+                                "uniqueItems": false,
+                                "minItems": 0,
                                 "items": {
                                   "type": "object"
                                 }
@@ -1885,8 +1885,8 @@
                         },
                         "stream": {
                           "type": "array",
-                          "uniqueItems": null,
-                          "minItems": null,
+                          "uniqueItems": false,
+                          "minItems": 0,
                           "items": {
                             "type": "object"
                           }
@@ -1899,14 +1899,14 @@
                     },
                     "timeline_lookup": {
                       "type": "array",
-                      "uniqueItems": null,
-                      "minItems": null,
+                      "uniqueItems": false,
+                      "minItems": 0,
                       "items": {
                         "properties": {
                           "0": {
                             "type": "array",
                             "uniqueItems": true,
-                            "minItems": null,
+                            "minItems": 0,
                             "items": {
                               "type": "object"
                             }
@@ -3621,8 +3621,8 @@
                   "properties": {
                     "user_badges": {
                       "type": "array",
-                      "uniqueItems": null,
-                      "minItems": null,
+                      "uniqueItems": false,
+                      "minItems": 0,
                       "items": {
                         "type": "object"
                       }
@@ -3798,8 +3798,8 @@
                         },
                         "featured_user_badge_ids": {
                           "type": "array",
-                          "uniqueItems": null,
-                          "minItems": null,
+                          "uniqueItems": false,
+                          "minItems": 0,
                           "items": {
                             "type": "object"
                           }
@@ -3864,8 +3864,8 @@
                   "properties": {
                     "user_badges": {
                       "type": "array",
-                      "uniqueItems": null,
-                      "minItems": null,
+                      "uniqueItems": false,
+                      "minItems": 0,
                       "items": {
                         "type": "object"
                       }
@@ -4041,8 +4041,8 @@
                         },
                         "featured_user_badge_ids": {
                           "type": "array",
-                          "uniqueItems": null,
-                          "minItems": null,
+                          "uniqueItems": false,
+                          "minItems": 0,
                           "items": {
                             "type": "object"
                           }
@@ -4734,8 +4734,8 @@
                           },
                           "posters": {
                             "type": "array",
-                            "uniqueItems": null,
-                            "minItems": null,
+                            "uniqueItems": false,
+                            "minItems": 0,
                             "items": {
                               "type": "object"
                             }
@@ -4745,16 +4745,16 @@
                     },
                     "users": {
                       "type": "array",
-                      "uniqueItems": null,
-                      "minItems": null,
+                      "uniqueItems": false,
+                      "minItems": 0,
                       "items": {
                         "type": "object"
                       }
                     },
                     "categories": {
                       "type": "array",
-                      "uniqueItems": null,
-                      "minItems": null,
+                      "uniqueItems": false,
+                      "minItems": 0,
                       "items": {
                         "type": "object"
                       }
@@ -4773,24 +4773,24 @@
                         },
                         "post_ids": {
                           "type": "array",
-                          "uniqueItems": null,
-                          "minItems": null,
+                          "uniqueItems": false,
+                          "minItems": 0,
                           "items": {
                             "type": "object"
                           }
                         },
                         "user_ids": {
                           "type": "array",
-                          "uniqueItems": null,
-                          "minItems": null,
+                          "uniqueItems": false,
+                          "minItems": 0,
                           "items": {
                             "type": "object"
                           }
                         },
                         "category_ids": {
                           "type": "array",
-                          "uniqueItems": null,
-                          "minItems": null,
+                          "uniqueItems": false,
+                          "minItems": 0,
                           "items": {
                             "type": "object"
                           }
@@ -6406,8 +6406,8 @@
                     },
                     "owners": {
                       "type": "array",
-                      "uniqueItems": null,
-                      "minItems": null,
+                      "uniqueItems": false,
+                      "minItems": 0,
                       "items": {
                         "type": "object"
                       }
@@ -7241,8 +7241,8 @@
                           },
                           "choices": {
                             "type": "array",
-                            "uniqueItems": null,
-                            "minItems": null,
+                            "uniqueItems": false,
+                            "minItems": 0,
                             "items": {
                               "type": "object"
                             }
1개의 좋아요

이 문제를 제기해 주셔서 감사합니다.

아니요, 현재 사용 가능한 스펙 파일은 이것뿐입니다.

다음 커밋에서 swagger 2.0에서 openapi 3.0으로 문서를 가져오기 위해 많은 변경 사항을 수행했습니다:

하지만 일부 항목이 누락되었거나 스펙의 새로운 변경 사항일 수 있습니다.

openapi-cli 명령줄 도구를 사용하여 다시 확인했는데, swagger 사이트와 유사한 오류를 재현할 수 있습니다:

blake@pop-os ~/code/discourse_api_docs (master) $ npx @redocly/openapi-cli lint openapi.json
...
❌ Validation failed with 647 errors and 579 warnings.

좋아 보입니다. 이러한 수정 사항으로 패치를 제출해 주시면 매우 감사하겠습니다. 또한 제가 일부 항목을 정리하는 데 도움을 드릴 수도 있습니다.

4개의 좋아요

천만에요. 기여 사항을 검토해 주셔서 감사합니다.

저희 SQL 엔진은 Discourse로 연결하기 위해 API를 커넥터로 사용하며, 이 커넥터는 수동 작성 대신 Swagger 기반으로 만들어졌습니다. 다만 아직 테스트 중인 단계입니다. 길이, 데이터 타입, null 허용 여부 등의 제약 조건 위반과 같은 문제를 발견할 수도 있습니다.

패치를 제출하는 것은 기꺼이 하겠지만, 팀이 제안된 변경 사항을 더 철저히 테스트할 수 있도록 며칠 정도 기다리겠습니다. 그렇지 않으면 효율이 낮으면서도 많은 시간을 차지하게 될 것 같아서요.

감사합니다!

3개의 좋아요

Pull request가 제출되었습니다. 실제로 실행되도록 작업 중인 과정에서 아래에 표시된 참조 테이블 값과 같은 추가 변경 사항이 발생할 수 있습니다.

3개의 좋아요

이 주제에 대해 마무리를 짓고자 합니다. 제출된 PR은 몇 가지 논의 끝에 폐기되었습니다.

다만, 줄바꿈 문제를 수정하는 커밋으로 후속 조치를 진행했습니다:

또한, 현재 OpenAPI json 스펙 파일을 자동으로 생성할 수 있는 도구인 rswag를 사용하여 API 문서를 Discourse 코드베이스와 더 긴밀하게 통합하는 작업이 진행 중임을 알려드립니다. 현재 문서에는 몇 가지 린팅 문제가 있지만, 이러한 문제들을 해결하는 데 도움이 될 rswag로의 전환을 완료하는 데 에너지를 집중하는 것이 가장 효과적이라고 생각합니다.

5개의 좋아요

그렇군요, 반가운 소식입니다! *.yaml 파일이나 유사한 파일은 처리할 수 없으나, 새로운 Swagger가 도입될 경우 철저히 테스트/검증해야 합니다. 알려주세요.

1개의 좋아요