Skip to content

.all(of:) loses nested schema definitions? #34

@Butanediol

Description

@Butanediol

When using OpenAPIParameters.all(of:...) to combine multiple query parameter types, nested schema definitions (like enums with custom openAPISchema) are referenced in parameters but not included in the OpenAPI components.schemas section, resulting in invalid OpenAPI specs with broken $ref links.

Here are some code from my project.

  1. Define an enum:
enum SortOption: String, Codable, CaseIterable, OpenAPIType {
    case relevance
    case count

    static var openAPISchema: SchemaObject {
        SchemaObject(
            description: "Sort options for query results",
            enum: allCases.map { AnyValue.string($0.rawValue) },
            context: .string
        )
    }
}

Side note: Can you elaborate how to deal with enums? I would assume the custom schema is not needed but sometimes I got error related to CodingKeys. So I added custom schema for them.

  1. Use this enum in a request DTO:
struct AppInfoQueryRequest: Content {
    let query: String?
    let sortBy: SortOption?
}
  1. Register a route with combined query parameters:
appInfo
    .get("search", use: search)
    .openAPI(
        summary: "Search for apps",
        query: .all(of: .type(AppInfoQueryRequest.self), .type(PageRequest.self)),
        response: .type(Page<AppInfoDTO>.self)
    )
  1. Generate and inspect the OpenAPI spec at /swagger endpoint

The generated OpenAPI spec should include the schema but this is what actually being generated:

{
  "name": "sortBy",
  "in": "query",
  "schema": {
    "$ref": "#/components/schemas/SortOption" // Correctly references the schema
  }
}
{
  "components": {
    "schemas": {
      // but SortOption is missing!
    }
  }
}

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions