swagger-api / swagger-api/swagger.io-docs

OAS 3 : allOf specification missing ?

Open
#318 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Astro
Stars
1.6k
Forks
407
Avg merge
2m
Merged PRs (30d)
2

Description

Hello Everyone,

I was wondering why the allOf at array level was not documented, because it is working perfectly :

(in the screenshot the swagger has been simplified for clarity purposes)

image

image

But because of the spec mentionned at https://spec.openapis.org/oas/latest.html :

4.8.24.2.1 Composition and Inheritance (Polymorphism) §
The OpenAPI Specification allows combining and extending model definitions using the allOf property of JSON Schema, in effect offering model composition. allOf takes an array of object definitions that are validated independently but together compose a single object.

While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, the OpenAPI Specification adds the discriminator field. When used, the discriminator will be the name of the property that decides which schema definition validates the structure of the model. As such, the discriminator field MUST be a required field. There are two ways to define the value of a discriminator for an inheriting instance.

My company is using those specs to validate swaggers, and because of that my AllOf is refused.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Compare the current swagger.io documentation with the OpenAPI Specification section on Composition and Inheritance linked in the issue, using the reported array-level allOf example as context. Confirm whether this valid usage is omitted, and consider the work done when the documentation accurately explains the supported form and its validation implications.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.