asmhatreandClaude Sonnet 5
8d0efb0d4b
Companion module for "springdoc-openapi with Spring Boot 4.1: Generating, Customising and Versioning Your API Spec". Reuses the ApiVersionConfigurer setup from the versioning-mechanics companion project and tests what springdoc-openapi 3.1.1 actually generates for a path with multiple version-scoped handlers: a default oneOf-merged operation with an arbitrary operationId, a working GroupedOpenApi + OpenApiCustomizer fix that collapses it to one clean schema per version, and a check of the officially-versioning-supported functional-endpoint path (springdoc v3.0.2's "Add support for Spring Framework API Versioning with Functional Endpoints"), which turns out to document only one of two registered versions rather than either version separately. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01M1uZDXWkY1MnTfQgt4HMeQ
160 lines
4.5 KiB
Plaintext
160 lines
4.5 KiB
Plaintext
GET /v3/api-docs (ungrouped, default), operation at /accounts/{id}:
|
|
operationId = getAccountV2 (picked from ONE of the three handlers, not versioned itself)
|
|
response schema = oneOf [3 entries]: #/components/schemas/AccountV1, #/components/schemas/AccountV2, #/components/schemas/AccountV1Point1
|
|
API-Version header enum (auto-documented) = ["2","1","1.0.0","1.1"]
|
|
API-Version header default = "1.0.0"
|
|
|
|
Full raw document:
|
|
{
|
|
"openapi" : "3.1.0",
|
|
"info" : {
|
|
"title" : "OpenAPI definition",
|
|
"version" : "v0"
|
|
},
|
|
"servers" : [ {
|
|
"url" : "http://localhost:36991",
|
|
"description" : "Generated server url"
|
|
} ],
|
|
"paths" : {
|
|
"/accounts/{id}" : {
|
|
"get" : {
|
|
"tags" : [ "account-controller" ],
|
|
"operationId" : "getAccountV2",
|
|
"parameters" : [ {
|
|
"name" : "id",
|
|
"in" : "path",
|
|
"required" : true,
|
|
"schema" : {
|
|
"type" : "string"
|
|
}
|
|
}, {
|
|
"name" : "API-Version",
|
|
"in" : "header",
|
|
"schema" : {
|
|
"type" : "string",
|
|
"default" : "1.0.0",
|
|
"enum" : [ "2", "1", "1.0.0", "1.1" ]
|
|
}
|
|
} ],
|
|
"responses" : {
|
|
"200" : {
|
|
"description" : "OK",
|
|
"content" : {
|
|
"*/*" : {
|
|
"schema" : {
|
|
"oneOf" : [ {
|
|
"$ref" : "#/components/schemas/AccountV1"
|
|
}, {
|
|
"$ref" : "#/components/schemas/AccountV2"
|
|
}, {
|
|
"$ref" : "#/components/schemas/AccountV1Point1"
|
|
} ]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/widgets/{id}" : {
|
|
"get" : {
|
|
"tags" : [ "widget-handler" ],
|
|
"operationId" : "getWidgetV1",
|
|
"responses" : {
|
|
"200" : {
|
|
"description" : "OK",
|
|
"content" : {
|
|
"*/*" : {
|
|
"schema" : {
|
|
"$ref" : "#/components/schemas/ServerResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"components" : {
|
|
"schemas" : {
|
|
"AccountV2" : {
|
|
"type" : "object",
|
|
"description" : "Account shape served by API version 2 — restructured, nested contact object",
|
|
"properties" : {
|
|
"accountId" : {
|
|
"type" : "string",
|
|
"description" : "Account identifier"
|
|
},
|
|
"displayName" : {
|
|
"type" : "string",
|
|
"description" : "Account holder display name"
|
|
},
|
|
"contact" : {
|
|
"$ref" : "#/components/schemas/Contact",
|
|
"description" : "Nested contact details, replacing the flat email field from 1.1"
|
|
},
|
|
"status" : {
|
|
"type" : "string",
|
|
"description" : "Lifecycle status, new in v2",
|
|
"enum" : [ "ACTIVE", "SUSPENDED", "CLOSED" ]
|
|
},
|
|
"apiVersion" : {
|
|
"type" : "string",
|
|
"description" : "Echoes the resolved API version"
|
|
}
|
|
}
|
|
},
|
|
"Contact" : {
|
|
"type" : "object",
|
|
"description" : "Contact details nested under an account, v2+",
|
|
"properties" : {
|
|
"email" : {
|
|
"type" : "string",
|
|
"description" : "Contact email"
|
|
}
|
|
}
|
|
},
|
|
"AccountV1" : {
|
|
"type" : "object",
|
|
"description" : "Account shape served by API version 1",
|
|
"properties" : {
|
|
"id" : {
|
|
"type" : "string",
|
|
"description" : "Account identifier"
|
|
},
|
|
"name" : {
|
|
"type" : "string",
|
|
"description" : "Account holder name"
|
|
},
|
|
"apiVersion" : {
|
|
"type" : "string",
|
|
"description" : "Echoes the resolved API version"
|
|
}
|
|
}
|
|
},
|
|
"AccountV1Point1" : {
|
|
"type" : "object",
|
|
"description" : "Account shape served from API version 1.1 onward (baseline handler)",
|
|
"properties" : {
|
|
"id" : {
|
|
"type" : "string",
|
|
"description" : "Account identifier"
|
|
},
|
|
"name" : {
|
|
"type" : "string",
|
|
"description" : "Account holder name"
|
|
},
|
|
"email" : {
|
|
"type" : "string",
|
|
"description" : "Contact email, added in 1.1"
|
|
},
|
|
"apiVersion" : {
|
|
"type" : "string",
|
|
"description" : "Echoes the resolved API version"
|
|
}
|
|
}
|
|
},
|
|
"ServerResponse" : { }
|
|
}
|
|
}
|
|
} |