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.
Related
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
I'm trying to use Go client to programmatically manage workflows. I'm using yaml, this is my workflow:
name: order-process
tasks:
- id: collect-money
type: payment-service
- id: fetch-items
type: inventory-service
switch:
- case: totalPrice > 100
goto: ship-parcel-with-insurance
- default: ship-parcel
- id: ship-parcel-with-insurance
type: shipment-service-premium
end: true
- id: ship-parcel
type: shipment-service
And when I deploy this, I can't visualize it in camunda operate, the page is stuck on loading
and I have this error in console:
Error: unparsable content detected
line: 0
column: 0
nested error: missing start tag
we are sorry but Operate only supports BPMN XML deployments at the moment. The YAML support in Zeebe is only rudimentary and not intended for real-world use cases. It becomes really hard to model complex processes with yaml, which is easily possible with BPMN. We highly encourage you to switch to the Zeebe Modeler to create your workflow models.
If you want to discuss this further, we are happy to welcome you in one of our community channels.
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 want to define REST resources in multiple files and include them in a single RAML file
I tried this but i always get RAML errors
Main.raml
#%RAML 1.0
title: Main RAML file to include All APIs
version: v1
baseUri: http://api.samplehost.com
/student: !include student.raml
student.raml
#%RAML 1.0
title: student APIs
version: v1
baseUri: http://api.samplehost.com
/student:
get: # ..etc
but I get Unknown Error in the included file: Unknown node: 'title' in Main.raml
when I remove the 'title' from the included file 'student.raml'
I got Unknown Missing required property 'title' in the student.raml file
According to raml-org issue, your student.raml file should have something like this:
get:
the important part here is removing the first line
#%RAML 1.0
I think it´s not possible to do this with RAML.
For me the Best way to accomplished this problem is to use the RAML Library and use resource types, traits and types to be associated with routes that you want to exposed.
For more information see RAML 1.0 documentation.