oneOf in Swagger schema does not work - yaml

I want to define PaymentMethod as below. Is oneOf supported in swagger.yaml?
PaymentMethod:
oneOf:
- $ref: '#/definitions/NewPaymentMethod'
- $ref: '#/definitions/ExistPaymentMethod'
The ExistPaymentMethod will have just id, and cardNumber where NewPaymentMethod will have no id, but all other details, e.g. cardNumber, cardholderName, cardholderAddress etc.

oneOf is supported in OpenAPI version 3 (openapi: 3.0.0), but not in Swagger version 2 (swagger: '2.0').
PaymentMethod:
oneOf:
- $ref: '#/components/schemas/NewPaymentMethod'
- $ref: '#/components/schemas/ExistPaymentMethod'
GitHub issue ref: https://github.com/OAI/OpenAPI-Specification/issues/333
For a list of changes in OpenAPI 3.0 compared to 2.0, see: https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/

What Swagger uses is only inspired by JSON Schema. They haven't deviated too much from JSON Schema, but they leave some things out, add some things, and change some behaviors. One of the things Swagger leaves out is oneOf.
More details can be found at http://swagger.io/specification/#schemaObject

OneOf, anyOf and other similar directives are not supported swagger 2.0, but supported in Open API 3.0 specifications.
You will need to convert your Swagger 2.0 file to Open API 3.0 file.
Here is the link -
https://blog.runscope.com/posts/tutorial-upgrading-swagger-2-api-definition-to-openapi-3
Here is one more useful link -
https://github.com/swagger-api/swagger-ui/issues/3803

Related

Laravel L5 Swagger "Package Unable to render this definition"

Upgraded from Laravel 8 to 9 and I received this message on swagger docs.
"Unable to render this definition
The provided definition does not specify a valid version field".
Please indicate a valid Swagger or OpenAPI version field.
Supported version fields are swagger: "2.0" and those that match OpenAPI : 3.0.n (for example, OpenAPI : 3.0.0)."
Some suggested adding
openapi="3.0.0"
line but where can I add? When I add in
#OA\Info()
it still throws an error like
Unexpected field "openapi" for #OA\Info()
Well, it is an invalid property on #OA\Info.
Are you sure you do not have a second annotation with that field somewhere?
It might be interesting to try run swagger-php on the command line against your codebase and see what that returns. Something like
./bin/openapi app
Also, what happens if you remove #OA\Info altogether. I would expect an error about it missing...?

Order Springdoc operation parameters alphabetically

Migrating from springfox - springdoc
springfox generated an openApi definition that ordered all the parameters in alphabetical order, I've migrated to springdoc, but have been unable to find a way to keep the springfox ordering(alpha) of the parameters, e.g.
Controller:
getPerson(name, address, mobile)
springfox generated openApi definition:
getPersonService(address, mobile, name)
springdoc generated openApi definition:
getPersonService(name, address, mobile)
There are properties to order other aspects of the generated definition with:
springdoc.swagger-ui.operationsSorter=method
springdoc.swagger-ui.tagsSorter=alpha
springdoc.writer-with-order-by-keys: true
I have been unable to find a property to order the operation parameters, is there a setting to accomplish this? or can it be achieved cleanly with:
OpenApiCustomiser or OperationCustomizer

YAML validation on API plaftform

I use API platform with YAML instead of Annotations. It's very easy to add validation constraint on Annotation but how add constraint in YAML. In the doc in Validation chapter I don't find. https://api-platform.com/docs/core/validation/#validation
API Platform uses the constraint validator from Symfony, you can refer to the symfony constraints documentation.
For example, using the Product sample from API platform with NotBlank constraint you should have:
# config/validator/validation.yaml
App\Entity\Product:
properties:
name:
- NotBlank: ~

Referencing configuration section from other place in spring-boot application.yaml

I'm configuring spring boot kafka streams in application.yaml. I need to configure properties of the output topics:
producer:
topic.properties:
cleanup.policy: compact
retention.ms: 604800000
Because I have the same configuration across the whole file I want to make single point where to define values:
my:
policy: compact
retention: 604800000
producer:
topic.properties:
cleanup.policy: ${my.policy}
retention.ms: ${my.retention}
But the topic.properties is just generic map passed to underlying kafka library. To make the configuration more flexible I would like to reference the my section from the producer.topic.properties. So when new kafka property is added then only my section is updated.
I tried:
producer:
topic.properties: ${my}
But this doesn't work - ${my} is replaced by my.toString() and configuration fails on getting String where Map is expected.
I'm looking for some section placeholder. For example in OpenAPI Spec you can do something similar to:
my:
policy: compact
retention: 604800000
producer:
topic.properties:
$ref: '/my'
I know basic YAML doesn't support references. But is there something in spring-boot allowing to reference other config sections?
You can reference other properties, but one at a time:
my:
policy: compact
retention: 604800000
producer:
topic.properties:
policy: ${my.policy}
retention: ${my.retention}

How to expose yaml endpoint in NSwag?

I need to expose the schema definition of API (.net core 2.2) in Yaml not JSON. I'm using NSwag. I found package NSwag.Core.Yaml https://www.nuget.org/packages/NSwag.Core.Yaml/
But I have no idea how I should use it. In Shwasbuckle things are pretty straightforward. Everything you have to do is change the extension to yaml, like this:
app.UseSwaggerUI(c => {
c.SwaggerEndpoint("/swagger/v1/swagger.yaml", "My API V1");
});
What should I do using NSwag?
Will be supported in next NSwag version:
https://github.com/RicoSuter/NSwag/issues/2331

Resources