Discourse openapi.json generate issue

[Kyle-Ye]

Context

I'd like to migrate my existing DiscourseKit to use swift-openapi-generator

After I download the latest discourse openapi.json from discourse_api_docs/openapi.json

I found its version is v3.1.0 and the plugin just emits an error telling me only 3.0.x is supported.

Then browsing the history of the git repo, I tried to use the latest openapi.json with v3.0.3
from this commit discourse_api_docs/openapi.json

But the result still gives me an error message saying "The given data was not valid YAML."

Is there anything wrong with the upstream data? Or maybe there is a bug in swift-openapi-generator.

Error: dataCorrupted(Swift.DecodingError.Context(codingPath: [], debugDescription: "The given data was not valid YAML.", underlyingError: Optional(Expected `items` value in .content['application/json'].schema.properties.badges for the status code '200' response of the **GET** endpoint under `/admin/badges.json` to be parsable as Mapping but it was not.)))
Swift OpenAPI Generator is running with the following configuration:
- OpenAPI document path: /.../DiscourseKit/Sources/DiscourseKit/openapi.json
- Configuration path: /.../DiscourseKit/Sources/DiscourseKit/openapi-generator-config.yaml
- Generator modes: types, client
- Output file names: Types.swift, Client.swift
- Output directory: /.../DiscourseKit-beyciueljvwcoocpkzbiovgfcson/SourcePackages/plugins/discoursekit.output/DiscourseKit/OpenAPIGenerator/GeneratedSources
- Diagnostics output path: <none - logs to stderr>
- Current directory: /.../DiscourseKit
- Is plugin invocation: true
- Additional imports: <none>

Reproduce code

Minimal reproduce code 👇

DiscourseKit.zip

[czechboy0]

The details seem to be in the error description on the first line:

Error: dataCorrupted(Swift.DecodingError.Context(codingPath: [], debugDescription: "The given data was not valid YAML.", underlyingError: Optional(Expected `items` value in .content['application/json'].schema.properties.badges for the status code '200' response of the **GET** endpoint under `/admin/badges.json` to be parsable as Mapping but it was not.)))

This error is coming from OpenAPIKit.

[czechboy0]

I see it, the issue is in the OpenAPI doc for discourse. The items key expects an object value, but there's an array wrapping that object value. Removing the array should fix it.

Might also be worth pasting the doc into an OpenAPI linter first, in case there are other issues.

[Kyle-Ye]

I see it, the issue is in the OpenAPI doc for discourse. The items key expects an object value, but there's an array wrapping that object value. Removing the array should fix it.

Might also be worth pasting the doc into an OpenAPI linter first, in case there are other issues.

Got it. So this should be a upstream issue from discourse_api_docs. I see there are many fix after it. But the fix also include upgrading the OpenAPI version from 3.0.3 to 3.1.0 2 years ago.

See Fix spec errors and update search endpoint

Hope swift-openapi-generator could support 3.1.x soon.

[Kyle-Ye]

The discussion of supporting OpenAPI v3.1.0 is tracked via #39.

From #39 (comment), I see v3.1.x was supported in the history of swift-openapi-generator.

Is there something we can config to reenable this feature?

[czechboy0]

We have never supported 3.1, but it's certainly planned.

Please comment in #39 about this use case, to make sure we can refer back to this thread. Otherwise, okay to close this issue in the meantime?

[Kyle-Ye]

Tried discourse openapi 3.1 file with my fork branch https://github.com/Kyle-Ye/swift-openapi-generator/tree/openapi_31x

Still get the "items" issue. I suspect maybe there is something wrong with the underlying OpenAPIKit or Yams.

[czechboy0]

Can you try with the YAML file? That seems to have the correct nesting as far as I can see: https://github.com/discourse/discourse_api_docs/blob/main/openapi.yml#L173-L177

[czechboy0]

The JSON file also seems correct from my reading: https://github.com/discourse/discourse_api_docs/blob/main/openapi.json#L170-L176

What's the exact error you're getting?

[Kyle-Ye]

I've tried both formats. And they will give me the same error

failed: caught error: "dataCorrupted(Swift.DecodingError.Context(codingPath: [], debugDescription: "The given data was not valid YAML.", underlyingError: Optional(Expected `items` value in .content['application/json'].schema.properties.form_template_ids for the request body of the **POST** endpoint under `/categories.json` to be parsable as Mapping but it was not.)))"

[Kyle-Ye]

Located the bug to be here https://github.com/mattpolzin/OpenAPIKit/blob/84f6702500fb00476d74420c1a0df64cddd3993e/Sources/OpenAPIKit/Schema%20Object/JSONSchemaContext.swift#L926

If we can't transform the issue(Since the 2 repo are not under the same team), I'll open issue on OpenAPIKit to track this.

// Input
{
  "form_template_ids": {
    "items": [],
    "type": "array"
  }
}

items = try container.decodeIfPresent(JSONSchema.self, forKey: .items) // ❌ Throw Error

[Kyle-Ye]

Close and transform the issue to mattpolzin/OpenAPIKit#277

[czechboy0]

Thanks – as @mattpolzin mentioned on that issue, I think both Swift OpenAPI Generator and OpenAPIKit are doing the right thing, and the OpenAPI doc is not valid. I don't think we should relax the type strictness, we want issues like this to be surfaced and fixed, rather than ignored and spread to more docs through copy-paste.

[Kyle-Ye]

Thanks – as @mattpolzin mentioned on that issue, I think both Swift OpenAPI Generator and OpenAPIKit are doing the right thing, and the OpenAPI doc is not valid. I don't think we should relax the type strictness, we want issues like this to be surfaced and fixed, rather than ignored and spread to more docs through copy-paste.

Discourse's openapi doc is generated by https://github.com/rswag/rswag. Maybe that repo is the final right place to report and fix the issue. 😂