bug: openapi schema is invalid

[vaintrub]

Describe the bug

The OpenAPI specification provided by Logto (downloaded from /api/swagger.json) is invalid and fails validation in multiple tools:
• swagger-cli validate
• @redocly/cli
• oapi-codegen
• openapi-generator
• go-swagger

The schema contains numerous structural violations of the OpenAPI standard, including:
• Duplicate path parameters
• Incorrect oneOf definitions
• Missing required $ref fields
• Illegal additional properties inside oneOf branches
• Invalid requestBody schemas
• Missing $ref in response schemas
• Schemas that do not satisfy exactly-one requirement in oneOf groups

As a result, it’s impossible to generate a correct client SDK for Logto using any OpenAPI-based code generator.

Expected behavior

The official OpenAPI schema should:
• Be valid according to the OpenAPI 3.x specification
• Pass validation using at least one of the standard validators (swagger-cli, redocly/cli, kin-openapi, openapi-generator-cli)
• Allow client SDK code to be generated
• Contain proper $ref definitions for all schemas
• Not duplicate path parameters
• Not contain incorrect oneOf objects
• Not include prohibited additionalProperties where not allowed

How to reproduce?

curl -fsSL http://localhost:3002/api/swagger.json -o logto.json
npx @redocly/cli lint logto.json

duplicate local parameter path/verificationId

#/paths/~1api~1sign-in-exp~1default~1check-password/post/responses/200/content/application~1json/schema/oneOf/1/properties/result must NOT have additional properties
#/paths/~1api~1sign-in-exp~1default~1check-password/post/responses/200/content/application~1json/schema/oneOf/1/properties/result must have required property '$ref'
#/paths/~1api~1organization-invitations/post/requestBody/content/application~1json/schema/properties/messagePayload/oneOf/1 must have required property '$ref'
#/paths/~1api~1custom-profile-fields/post/requestBody/content/application~1json/schema must match exactly one schema in oneOf
...

Environment

Self-hosted (Docker image)

Screenshots

No response

[charIeszhao]

Thanks for reporting. We'll take a look.

[vaintrub]

@charIeszhao

We suddenly needed an management API, so I started implementing it -> https://github.com/vaintrub/logto-go

I thought I could implement it centrally with you 😊
What do you think of the idea? Perhaps you see it differently.