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.
Related
I would like to be able to validate OAS3.X compatible YAML spec files against the OAS3.0 spec (https://spec.openapis.org/oas/v3.1.0). The built-in capabilities in swagger-parser and openapi4j appear to give inconsistent results. For instance the swagger-parser is not flagging that 'decimal' is not a valid data type in OAS3 etc. How could I write a validator from scratch in Java that would load the OAS3 spec and then validate the YAML spec files against it? (Note: In openapi4j, if the URL points to the OAS3.0 spec file, the parser quits with an exception.)
Thanks!
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
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´m having problems using an (apparently) valid YML file with Spring Cloud Config as soon as I try to use anything like list or sequences.
Some dummy YML samples. This one works when I hit the endpoint exposed by the server:
info:
description: "This is the collector for CEM"
git-commit: "bla bla MD5"
version: "0.2.0-SNAPSHOT"
This one does not work:
info:
description: "This is the collector for CEM"
git-commit: "bla bla MD5"
version: "0.2.0-SNAPSHOT"
items: [ "a", "b", "c"]
Tried this as well:
info:
description: "This is the collector for CEM"
git-commit: "bla bla MD5"
version: "0.2.0-SNAPSHOT"
items:
- "a"
- "b"
- "c"
The error I get with the second and third examples is this one:
This page contains the following errors:
error on line 1 at column 462: StartTag: invalid element name
Below is a rendering of the page up to the first error.
What would be the correct way of using lists/sequences? I am mostly interested in lists of complex objects and, unfortunately, the samples provided are almost always one-liners.
Cheers!
Update: I fixed a badly written example (the third one). I still does not work.
Update 2: This is actually an issue with the HTML renderer and not with the functionality of the config server itself, as it passes the config to the client without issue. However the HTML is a nice-to-have as it gives you visual information on what is being loaded.
Update 3: I´m using Spring Cloud Brixton.SR7
You could try with:
items:
- a
- b
- c
The issue seems to be removed pulling the latest version of Spring Cloud Config. However, now JSON is displayed instead of XML.