ePages-de / ePages-de/restdocs-api-spec
Add `oneOf` composite schema support?
- Dominant language
- Kotlin
- Stars
- 427
- Forks
- 116
- Avg merge
- 23h 54m
- Merged PRs (30d)
- 1
Description
Currently we seems to always aggregate `FieldDescriptors` for different requests with the same path + method + mediaType, which is fine in most cases. However, in our case, we have an API that supports multiple schemas (within the same path + method + mediaType) by using a [discriminator type polymorphism](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#discriminator-object) approach.
I created a [simple pet demo branch](https://github.com/lzhoucs/restdocs-api-spec/tree/oneof-pet-demo) for demo.
Currently the generated api spec looks like:
```yaml
paths:
/pet-demo:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/pet-demo-1939693445'
components:
schemas:
pet-demo-1939693445:
type: object
properties:
dogProp:
type: string
description: A dog specific property
petType:
type: string
description: cat
name:
type: string
description: Name of cat
catProp:
type: string
description: A cat specific property
```
Expected api spec:
```yaml
paths:
/pet-demo:
post:
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/cat'
- $ref: '#/components/schemas/dog'
discriminator:
propertyName: petType
components:
schemas:
cat:
type: object
properties:
petType:
type: string
description: cat
name:
type: string
description: Name of cat
catProp:
type: string
description: A cat specific property
dog:
type: object
properties:
petType:
type: string
description: dog
name:
type: string
description: Name of dog
dogProp:
type: string
description: A dog specific property
```
Swagger UI recognizes it and render the `oneOf` composite schemas as follows:

Please let me know if there's any question. I can add more details if anything above is not clear.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.