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.
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"
}
}
}
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
We have upgraded to the Crowd Release platform and are now creating API specifications which are using fragments as recommended by MuleSoft. However, we can import the RAML but can not generate the flows. There is no error - no warnings - nothing.
I have included an example.
api.raml
#%RAML 1.0
version: v1
title: api
types:
contactDetails: !include library/types/contactDetails.raml
/contact:
post:
body:
application/json:
type: contactDetails
types-library.raml
#%RAML 1.0 Library
types:
telephoneNumber: !include ../exchange_modules/fragment-flows-problem-fragment/1.0.0/telephone-number.raml
contactDetails.raml
#%RAML 1.0 DataType
uses:
contactDetails: ../types-library.raml
properties:
name:
type: string
telephone:
type: contactDetails.telephoneNumber
telephone-numbers.raml (fragment)
#%RAML 1.0 DataType
description: |
**includes validation applicable to a contact telephone number**
***
- Minimum length 9
- Maximum length 15
type: string
displayName: Telephone Number
minLength: 9
maxLength: 15
pattern: ^[\d ]+$
examples:
telephoneNumber1: "01433000000"
telephoneNumber2: "01433 000000"
I'll just add that the RAML is valid in both Design Center and Exchange.
Just to add, if we remove the uses statement in the contactDetails.raml, then the contactDetails data type is not recognised.
If someone point out a problem here or explain how Anypoint Studio can import specifications which utilise fragments that would be extremely useful.
Thanks.
This is a late reply but I happened to run into this problem today and my search led me to your question.
The problem for me is a missing !include in the contactDetails.raml file. I had the same problem in Anypoint Studio and my fix would be:
#%RAML 1.0 DataType
uses:
contactDetails: !include ../types-library.raml
properties:
name:
type: string
telephone:
type: contactDetails.telephoneNumber
Anypoint Studio unfortunately doesn't give any good information on why there is a RAML error, but just tells you something is wrong.
I'm trying to simplify this data:
farm:
- pets:
- type: fish
breedtype: fish
name: dory
- type: dog
breedtype: dog
name: lassie
Basically type and breedtype are always the same, unfortunately this is the case.
I've tried to simplify this by somehow using anchors
base: &base
type: &type fish
breedtype: *type
farm:
type: &type dog
<<: *base
I want the *base to inherit &type from &type dog.
I'm not sure if this is the right approach or if there's an easier way, am I looking at the problem wrong?
While it is true that YAML defines a << type, be aware that this is not part of the specification, but part of the type repository which is based on the outdated YAML version 1.1 and has not been updated since. A YAML implementation is not required to support this type. Moreover, it does not do what you think it does, because the alias *type is resolved in the context where it occurs and will always link to the value fish.
Be aware that YAML is pure data. It is not capable of nor designed to enforce rules like type always must match breedtype. The schema used for loading the data is defined by the one loading it. If in your data schema, type always equals breedtype, you can just leave out breedtype in YAML, because when loading it into an application, you can set its value from type.