I am a little confused by Swagger's enum support for OpenAPI3.0. My point here being that there have been new improvements in swagger doc where there is support for re-usable enums as
documented here:
https://swagger.io/docs/specification/data-models/enums/
where support for reusable enums is stated using $ref. However, when I post my swagger.json to swagger editor/validator which looks like following
in: query
name: prop-name
description: something
type: array
items:
$ref: '#/definitions/mytype'
which is further defined below:
mytype:
enum:
- Item1
type: string
Swagger editor throws an error and says should NOT have additional properties
additionalProperty: $ref
Now, this is not a problem when loading the swagger page and attaining the functionality but it is an issue when it comes to using swagger-gen and generating clients using it. the swagger-gen CLI also throws the same error causing us to now being able to generate a client for this page correctly.
Is there anything wrong with this swagger.json? I there any extra information that I can provide to shed light on this issue?
In OpenAPI 2.0, array parameter schemas cannot use $ref. You must define the enum inline:
- in: query
name: prop-name
description: something
type: array
items:
type: string
enum:
- Item1
Related
I'm new in swagger.
I have a few yaml files and I try to genetare code, using swagger plugin in Intellij.
When I generate it, I have errors cannot find symbol. The symbol that he can't find is
TS29510NnrfNFManagementYamlcomponentsschemasFqdn
But this is wrong. Really he is looking for symbol
$ref: TS29510_Nnrf_NFManagement.yaml#/components/schemas/Fqdn
Fqdn is not generated (I think because it's type is not object).
But why generator can't find this symbol?
In yaml Fqdn looks like this:
Fqdn:
type:
- string
- array
items: {}
You basically answered yourself. Object Fqdn is invalid that's why it can't generated or referenced. Simply change object declaration and enjoy working code :)
Fqdn:
type: object
properties:
items:
type: array
items:
type: string
I am developing an application with an Angular frontend and RESTful Spring Boot Backend
I found this very handy maven plugin openapi-generator-maven-plugin from org.openapitools. With its code generation capability, it helps enforce a "contract first" approach between the frontend and backend for our API. But our swagger file uses "oneOf" property in the requestBody and responseBody definitions. I've tried to generate Spring code from this, but the generated Java class has missing imports:
import com.pack.api.dto.OneOfLatteCoffeAmericanoCoffe;
import com.pack.api.dto.UNKNOWN_BASE_TYPE;
Is there away to cofigue the plugin to work with Swagger's oneOf property? I'm usig Spring Boot 2.3.1, Swagger 3.0 and Openapi-generator-maven-plugin 4.3
Currently, openapi-generator doesn't support oneOf. This is a capability that had been newly introduced with OpenAPI v3 (FYI, only v2 and below are called "Swagger", it has then been renamed to OpenAPI). There are various generators (Java, Spring, lots of other languages). I have seen that contributions have been made during this year to enable oneOf support.
To sum up, it looks like you have to wait a bit more until you can exploit this feature of the OpenAPI v3 spec using the generator for Spring.
Edit: It's also listed on the "short term roadmap":
OAS3.0 features support: anyOf, oneOf, callbacks, etc
If you can modify your swagger, you may replace the oneOf with a reference to an abstract type.
For example, if your swagger looks like this :
components:
schemas:
'Parent':
'vehicle':
oneOf:
- type: object
properties:
'car_property':
type: string
- type: object
properties:
'truck_property':
type: string
You can modify it like that :
components:
schemas:
'Parent':
type: object
properties:
'vehicle':
$ref: '#/components/schemas/Vehicle'
#---------------------------------------------------------------------------
# Abstract class with discriminator 'vehicle_type'
#---------------------------------------------------------------------------
'Vehicle':
type: object
properties:
'vehicle_type':
type: string
enum: [ 'CAR', 'TRUCK' ]
discriminator:
propertyName: vehicle_type
mapping:
'CAR': '#/components/schemas/Car'
'TRUCK': '#/components/schemas/Truck'
#---------------------------------------------------------------------------
# Concrete classes
#---------------------------------------------------------------------------
'Car':
allOf:
- $ref: "#/components/schemas/Vehicle"
- type: object
properties:
'car_property':
type: string
'Truck':
allOf:
- $ref: "#/components/schemas/Vehicle"
- type: object
properties:
'truck_property':
type: string
This swagger modification makes the generator work. It handles the same JSON objects though I am not 100% sure it is semanticaly equivalent in OpenAPI specification.
We've added better oneOf and anyOf support to some generators such as java (okhttp-gson, jersey2, native), csharp-netcore, Go, PowerShell, R and more. Please give it a try with the latest master. SNAPSHOT versions can be found in the project's README: https://github.com/OpenAPITools/openapi-generator/
I using #openapitools/openapi-generator-cli and i tried this java snapshot https://oss.sonatype.org/content/repositories/snapshots/org/openapitools/openapi-generator-cli/6.0.0-SNAPSHOT/openapi-generator-cli-${versionName}.jar and it worked for me.
Just need setup openapitools.json like this -
{
"$schema": "./node_modules/#openapitools/openapi-generator-cli/config.schema.json",
"spaces": 2,
"generator-cli": {
"version": "6.0.0-20211025.061654-22",
"repository": {
"downloadUrl": "https://oss.sonatype.org/content/repositories/snapshots/org/openapitools/openapi-generator-cli/6.0.0-SNAPSHOT/openapi-generator-cli-${versionName}.jar"
}
}
}
The issue with creating documentation when using re-usable enums
My yaml file looks like this
openapi: 3.0.2 components: schemas:
Countries:
type: string
enum:
- Unknown
- Afghanistan
- Albania
- Algeria
- American Samoa
- "\u00c5landIslands"
- NotOtherwiseSpecified
, when I compile it creates the java classes correctly, however, is not creating the documentation, just gives me:
Countries-
and nothing more is displayed for that particular scheme. For the other schemes enum options are displayed, etc.
Can you help me with this problem? Is this an issue of swagger or I am mistaken somewhere. The example in the swagger website and my code are following the same rules: https://swagger.io/docs/specification/data-models/enums/.
I also posted similar question here: https://community.smartbear.com/t5/SwaggerHub/Issue-with-creating-a-documentation-when-using-re-usable-enums/m-p/191938
P.S. I thought the problem is coming because of the special character, but it is not. I tried without that specific enum entry and also I have another similar way reusable enum that behaves the same way.
This is working fine for me. I am attaching an example for reference of how I am doing it.
Parameters in route.yaml
parameters:
- name: Country
in: query
required: true
schema:
$ref: "#/components/schemas/test"
Declaration in parameters.yaml
components:
schemas:
test:
type: string
enum:
- Unknown
- Afghanistan
- Albania
- Algeria
- "\u00c5landIslands"
Attaching the image from Swagger UI
Please add some more details for reference as above mentioned are working fine for me.
I am using grape-swagger to show documentation on my Ruby API i'm building using Grape.
I am adding descriptions to all of my parameters on my endpoints but I can't seem to find anything about how to add descriptions to route parameters.
I have tried the following:
route_param :monitor_name, type: String, desc: 'The name of the monitor that is being retrieved.' do
and
route_param :monitor_name, type: String, description: 'The name of the monitor that is being retrieved.' do
but neither of those will display the actual description on the swagger UI.
Any ideas?
Thanks for the help!
p.s. (the only thing I found in the grape documentation is shown in the attach image)
You could use
route_param :monitor_name, type: String, documentation: { desc:'The name of the monitor that is being retrieved.' }
I'm writing some RAML in an API designer and I have the following code:
/users:
/{id}:
/tags:
description: Personal tags of a user
get:
description: A list of the user's personal tags
responses:
200:
body:
application/json:
example: |
{
tags: [
{...},
...
]
}
/{slug}:
description: A personal tag
put:
The parser is throwing an error at /{slug} because it thinks that I'm trying to use it as a property of the get: method. However, /{slug} needs to be indented to make it subordinate to /tags.
Is there a way in RAML (or YAML, since RAML is supposed to be an instance of YAML), to mark the end of a map? Or do you have any other suggestions?
RAML doesn't (AFAIK) support explicit termination of maps, but we also don't need that to solve your problem :-).
Since in YAML the whitespace is semantic, what's happening is that your GET method is currently indented such that it's a method on the /users/{id} level, so even though it looks like /{slug} is subordinate to tags, it thinks it is in the definition of /users/{id} Really, we should probably throw an error here, since the method definition comes after you've defined a sub-resource (thanks for finding this case).
To solve, all you need to do is indent your description and get definition for /users/{id}/tags one additional level, and it should all parse fine. Updated RAML is below.
/users:
/{id}:
/tags:
description: Personal tags of a user
get:
description: A list of the user's personal tags
responses:
200:
body:
application/json:
example: |
{
tags: [
{...},
...
]
}
/{slug}:
description: A personal tag
put: