ePages-de / ePages-de/restdocs-api-spec

Add `oneOf` composite schema support?

Open
#97 2 comments 0 reactions 0 assignees View on GitHub
question
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:
![image](https://user-images.githubusercontent.com/1444104/56859481-3bea7780-6951-11e9-9877-fd34c38fc075.png)

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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.