Contributions
Reducing redundant endpoint definitions
Hey forum, I have a design question concerning the best practise for the following scenario. I have a bunch of endpoints defined in my OpenAPI specification, but actually double what really ought to be fully defined. These operations apply to specific entities (let's say songs for the sake of example). Each song has a unique database assigned numeric song_id, but also has a freeform unique text "reference" that the client assigns when adding the song to the database. When a request is made to an endpoint that uses a song_reference, the server translates the reference into a song_id and then performs the request. The song_reference endpoints are effectively just wrappers for the song_id endpoints. I don't want to have to define two sets of operations for what's effectively the same endpoints under the hood. I have reproduced a minimal below: openapi: "3.0.1" info: title: "Some API" version: "0.1" paths: /songs/download/by_id/{song_id}: get: summary: "Download a song by ID." operationId: getSongDownloadById parameters: - name: song_id in: path explode: false required: true description: "ID of song to download." schema: $ref: "#/components/schemas/song_id" example: 1434 responses: 200: description: "Operation successful" content: application/octet-stream: schema: type: string format: binary example: "...file's raw binary data..." 304: description: "Not modified" 404: description: "Not found response." # Redundant endpoint definition below which is exactly the same except expects song_reference. /songs/download/by_reference/{song_reference}: get: summary: "Download a song by reference." operationId: getSongDownloadByReference parameters: - name: song_reference in: path explode: false required: true description: "Reference of song to download." schema: $ref: "#/components/schemas/song_reference" example: "some_reference" responses: 200: description: "Operation successful" content: application/octet-stream: schema: type: string format: binary example: "...file's raw binary data..." 304: description: "Not modified" 404: description: "Not found response" components: schemas: song_id: type: "integer" description: "Database assigned unique song ID." song_reference: type: "string" description: "Similar to song ID, but assigned by client when song added to database. Unique." My goal is of course to reduce redundancy in the specification. Suggestions?Solved1.2KViews0likes2Commentsschema via oneOf with additional common properties
Hey everyone, I am trying to achieve the following, but with the commented lines uncommented. Uncommented it is not syntactically correct, but semantically I am trying to add BodyCommon's properties to the POST body, in addition to either BodyTypeA or BodyTypeB. openapi: "3.0.1" info: servers: paths: components: requestBodies: SomeClientPostBody: required: true content: application/json: schema: oneOf: - $ref: "#/components/schemas/BodyTypeA" - $ref: "#/components/schemas/BodyTypeB" # properties: # $ref: "#/components/schemas/BodyCommon" schemas: BodyTypeA: properties: type_a_property: type: integer BodyTypeB: properties: type_b_property: type: string BodyCommon: properties: common_property: type: integer How can I fix this?Solved2.9KViews0likes2Comments