Generating from GitHub OpenAPI spec fails to accept 3.0.3 version

[t089]

On a brand new Swift package I was trying to generate a client from the GitHub OpenAPI spec:
https://github.com/github/rest-api-description/blob/main/descriptions/api.github.com/api.github.com.yaml

The generation fails with a couple of errors in the YAML that can be easily patched, but one in particular is unexpected.

The YAML states in the beginning:

---
openapi: 3.0.3
info:
  version: 1.1.4
  title: GitHub v3 REST API
  description: GitHub's v3 REST API.
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  termsOfService: https://docs.github.com/articles/github-terms-of-service
  contact:
    name: Support
    url: https://support.github.com/contact?tags=dotcom-rest-api
  x-github-plan: api.github.com

Yet, the generator outputs the following:

String does not match the pattern of "^3\.1\.\d+(-.+)?$".

By why does it try to match against 3.1.x?

swift-driver version: 1.75.2 Apple Swift version 5.8 (swiftlang-5.8.0.124.2 clang-1403.0.22.11.100)
Target: x86_64-apple-macosx13.0

[t089]

Ok, maybe this error is not actually coming from the plugin. I realized that there are others errors in the build terminal. Eg:

Building for debugging...
Error: Disallowed value for a string enum 'Components.Schemas.check_suite.conclusionPayload (#/components/schemas/check-suite/conclusion)': ()

This was caused by enums that contain an empty value:

enum:
- value 1
- 

, I started to patch them one by one, but it is too much :( Maybe it would be a good idea to run the generator against some "well-known" specs (eg. GitHub, k8s, ...)?!

[simonjbeaumont]

@t089 Thanks for trying it out, and for taking the time to file an issue.

Maybe it would be a good idea to run the generator against some "well-known" specs (eg. GitHub, k8s, ...)?!

As you might imagine, we have run it against OpenAPI documents for many well-known APIs. AFAIK Kubernetes works as-is, as do many other well-known APIs. But, as you've noticed, the Github API has some identifiers in which are problematic.

While it can currently support a number of popular APIs already, we are continuing our development in the open as we progress to a 1.0 release, allowing us to prioritise the features according to demand and with community feedback.

We're incrementally adding support for various features in the OpenAPI specification. The documentation here expands on the progress: https://swiftpackageindex.com/apple/swift-openapi-generator/0.1.3/documentation/swift-openapi-generator/supported-openapi-features.

Relevant to the Github API, we added support for empty identifiers in #59 but we are aware the Github API has additional issues with the use of +1 and -1 as operation identifiers and a problematic oneOf. We have an open proposal to deterministically handle identifiers that aren't legal in Swift (#95), which is currently in review to get some community feedback.

, I started to patch them one by one, but it is too much :(

Here's a patch against the Github OpenAPI document that might serve as a workaround for you in the meantime, which is based on https://github.com/github/rest-api-description/blob/main/descriptions/ghes-3.3/ghes-3.3.yaml:

diff -u ghes-3.3.yaml openapi.yaml (click to unfold)

--- original.yaml	2023-07-06 20:08:38
+++ openapi.yaml	2023-07-06 20:03:12
@@ -10503,7 +10503,6 @@
           type: string
           enum:
           - "+1"
-          - "-1"
           - laugh
           - confused
           - heart
@@ -10562,7 +10561,6 @@
                     to add to the team discussion comment.
                   enum:
                   - "+1"
-                  - "-1"
                   - laugh
                   - confused
                   - heart
@@ -10653,7 +10651,6 @@
           type: string
           enum:
           - "+1"
-          - "-1"
           - laugh
           - confused
           - heart
@@ -10711,7 +10708,6 @@
                     to add to the team discussion.
                   enum:
                   - "+1"
-                  - "-1"
                   - laugh
                   - confused
                   - heart
@@ -18295,7 +18291,6 @@
           type: string
           enum:
           - "+1"
-          - "-1"
           - laugh
           - confused
           - heart
@@ -18354,7 +18349,6 @@
                     to add to the commit comment.
                   enum:
                   - "+1"
-                  - "-1"
                   - laugh
                   - confused
                   - heart
@@ -22605,7 +22599,6 @@
           type: string
           enum:
           - "+1"
-          - "-1"
           - laugh
           - confused
           - heart
@@ -22664,7 +22657,6 @@
                     to add to the issue comment.
                   enum:
                   - "+1"
-                  - "-1"
                   - laugh
                   - confused
                   - heart
@@ -23653,7 +23645,6 @@
           type: string
           enum:
           - "+1"
-          - "-1"
           - laugh
           - confused
           - heart
@@ -23714,7 +23705,6 @@
                     to add to the issue.
                   enum:
                   - "+1"
-                  - "-1"
                   - laugh
                   - confused
                   - heart
@@ -25797,7 +25787,6 @@
           type: string
           enum:
           - "+1"
-          - "-1"
           - laugh
           - confused
           - heart
@@ -25856,7 +25845,6 @@
                     to add to the pull request review comment.
                   enum:
                   - "+1"
-                  - "-1"
                   - laugh
                   - confused
                   - heart
@@ -29545,7 +29533,6 @@
           - comments
           - reactions
           - reactions-+1
-          - reactions--1
           - reactions-smile
           - reactions-thinking_face
           - reactions-heart
@@ -31011,7 +30998,6 @@
           type: string
           enum:
           - "+1"
-          - "-1"
           - laugh
           - confused
           - heart
@@ -31072,7 +31058,6 @@
                     to add to the team discussion comment.
                   enum:
                   - "+1"
-                  - "-1"
                   - laugh
                   - confused
                   - heart
@@ -31128,7 +31113,6 @@
           type: string
           enum:
           - "+1"
-          - "-1"
           - laugh
           - confused
           - heart
@@ -31188,7 +31172,6 @@
                     to add to the team discussion.
                   enum:
                   - "+1"
-                  - "-1"
                   - laugh
                   - confused
                   - heart
@@ -38185,8 +38168,6 @@
         total_count:
           type: integer
         "+1":
-          type: integer
-        "-1":
           type: integer
         laugh:
           type: integer
@@ -38204,7 +38185,6 @@
       - url
       - total_count
       - "+1"
-      - "-1"
       - laugh
       - confused
       - heart
@@ -40288,7 +40268,6 @@
         the alert."
       nullable: true
       enum:
-      - 
       - false_positive
       - wont_fix
       - revoked
@@ -41194,7 +41173,6 @@
           type: string
           enum:
           - "+1"
-          - "-1"
           - laugh
           - confused
           - heart
@@ -44855,7 +44833,6 @@
           - action_required
           - startup_failure
           - stale
-          - 
           nullable: true
         url:
           type: string
@@ -44977,7 +44954,6 @@
         or closing the alert."
       nullable: true
       enum:
-      - 
       - false positive
       - won't fix
       - used in tests
@@ -54173,7 +54149,6 @@
     emojis-get:
       value:
         "+1": https://github.githubassets.com/images/icons/emoji/unicode/1f44d.png?v8
-        "-1": https://github.githubassets.com/images/icons/emoji/unicode/1f44e.png?v8
         '100': https://github.githubassets.com/images/icons/emoji/unicode/1f4af.png?v8
         '1234': https://github.githubassets.com/images/icons/emoji/unicode/1f522.png?v8
         1st_place_medal: https://github.githubassets.com/images/icons/emoji/unicode/1f947.png?v8
@@ -59108,7 +59083,6 @@
           url: https://api.github.com/teams/2343027/discussions/1/reactions
           total_count: 5
           "+1": 3
-          "-1": 1
           laugh: 0
           confused: 0
           heart: 1
@@ -59156,7 +59130,6 @@
           url: https://api.github.com/teams/2343027/discussions/1/reactions
           total_count: 5
           "+1": 3
-          "-1": 1
           laugh: 0
           confused: 0
           heart: 1
@@ -59204,7 +59177,6 @@
           url: https://api.github.com/teams/2343027/discussions/1/reactions
           total_count: 5
           "+1": 3
-          "-1": 1
           laugh: 0
           confused: 0
           heart: 1
@@ -59247,7 +59219,6 @@
           url: https://api.github.com/teams/2403582/discussions/1/reactions
           total_count: 5
           "+1": 3
-          "-1": 1
           laugh: 0
           confused: 0
           heart: 1
@@ -59290,7 +59261,6 @@
           url: https://api.github.com/teams/2403582/discussions/1/reactions
           total_count: 5
           "+1": 3
-          "-1": 1
           laugh: 0
           confused: 0
           heart: 1
@@ -59333,7 +59303,6 @@
           url: https://api.github.com/teams/2403582/discussions/1/reactions
           total_count: 5
           "+1": 3
-          "-1": 1
           laugh: 0
           confused: 0
           heart: 1
@@ -66843,7 +66812,6 @@
           url: https://api.github.com/repos/github/roadmap/issues/comments/1130876857/reactions
           total_count: 0
           "+1": 0
-          "-1": 0
           laugh: 0
           hooray: 0
           confused: 0
@@ -72791,9 +72759,7 @@
         as a string.
       required: true
       schema:
-        oneOf:
-        - type: integer
-        - type: string
+        type: string
     autolink-id:
       name: autolink_id
       description: The unique identifier of the autolink.

Did you confirm that the error message String does not match the pattern of "^3\.1\.\d+(-.+)?$". was a red herring?

[t089]

Thank you so much for the detailed answer and for the patch, really appreciate it!

I can confirm that this error was indeed because there was some other plugin in VSCode that validated the schema and was set to OpenApi v3.1 🤦‍♂️