I'm trying to make a custom rule based on the unkown-error-format that can be found here here. Using this Open API document as an example:
openapi-generated.yaml
openapi: 3.0.3
info:
title: API
version: 1.0.0
servers:
- url: https://api.com/
paths:
/:
get:
tags: []
summary: Your GET endpoint
description: Your GET endpoint
operationId: get-endpoint
responses:
"500":
description: Error
content:
application/json:
schema:
properties:
errorDescription:
type: string
and this rule set:
.spectral.yml
extends:
- https://raw.githubusercontent.com/openapi-contrib/style-guides/master/apisyouwonthate.yml
rules:
unknown-error-format: error
When running
spectral lint --ruleset .spectral.yml openapi-generated.yaml
I was expecting an error to be returned, because the 500 response content is application/json and not one of the allowed values application/vnd.api+json, application/problem+xml, and application/problem+json.
Instead no errors are found:
No results with a severity of 'error' or higher found!
I experimented with some other Spectral core functions that should make the linter return an error, but it does not. I suspect the expression in given is not returning the right result, internally.
Additionally, I tried using this JSON Path Demo to check if the output array with "application/json" is returned for the path in the rule's given. It does.
Is there a problem with this rule or am I doing something wrong?
I'm using Spectral version 6.1.0.
Thanks in advance.
Related
I'm using OAS3 generator for Java as a Maven plugin to generate POJOs, controllers, delegates etc for my APIs with the Mustache templates from the openapi-generator repository: https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/main/resources/JavaSpring/apiController.mustache
I'm trying to edit this template so that the "#Controller" annotation is generated only if a condition is met. I've searched for multiple solutions for this and one of them was using "vendorExtensions".
I've made the following contract with x-generateController vendorExtension:
openapi: 3.0.0
info:
title: User API
description: API for user changes
contact:
name: xxx
url: xxx
email: xxx
license:
name: xxx
url: xxx
version: 1.0.0
tags:
- name: user
x-generateController: True
paths:
/users:
...
And then in the Mustache template file I have put the following:
{{#vendorExtensions.x-generateController}}
#Controller("{{classname}}")
{{/vendorExtensions.x-generateController}}
The generator works just fine without this condition but it seems like it doesn't take into account x-generateController. In fact, if I try to just place it as a comment like this:
// {{vendorExtensions.x-generateController}}
I get only "// " and an empty space. I've also tried putting it at the "endpoint level" and not in the "info level" and the problem is the same.
Is there anything more that I should've done in the configuration? Is there any alternative for a condition in the Mustache template?
I'm just starting to use Swagger Editor/OpenAPI 3 spec and so it's not going good so far. I have installed and running Swagger Editor v. 3.15.2 on my local machine.
This is the yaml I have so far:
openapi: "3.0.0"
info:
version: 1.0.0
title: Test
paths:
/object:
post:
summary: Create an object
operationId: createObject
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Object"
responses:
'201':
description: Created
components:
schemas:
Object:
required:
- name
- description
properties:
name:
type: string
description:
type: string
And it's displaying this error:
Errors
Resolver error
e is undefined
Structural error at paths./object
should NOT have additional properties
additionalProperty: responses
Jump to line 6
Structural error at paths./object.post
should have required property 'responses'
missingProperty: responses
Jump to line 7
I have ensured that I am using two spaces for all the indents. When I copied the yaml from the editor and put it into Notepad++ it looked fine. I also pasted it into another editor and noticed that it only used line feeds and not carriage returns. I updated it to use both and still get the same error.
I have looked at other questions with the same problem but none of the solutions worked for me. So, not sure what I'm doing wrong. Any guidance is greatly appreciated.
You have a small indentation problem.
Add one indentation level to
responses:
'201':
description: Created
So that you then have:
openapi: "3.0.0"
info:
version: 1.0.0
title: Test
paths:
/object:
post:
summary: Create an object
operationId: createObject
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Object"
responses:
'201':
description: Created
components:
schemas:
Object:
required:
- name
- description
properties:
name:
type: string
description:
type: string
Suppose I have an OpenAPI 3 document describing API Foo as follows:
openapi: 3.0.0
info:
version: '1'
title: Foo
paths:
/foo:
get:
responses:
200:
description: A Foo
post:
responses:
201:
description: Foo created
In another OpenAPI document for API Bar, I would like to reference only the GET /foo operation from API Foo. The OpenAPI docs talk a little about referencing a whole path. However, if I do the following:
openapi: 3.0.0
info:
version: '1'
title: Bar
paths:
/foo:
$ref: 'foo.yaml#/paths/~1foo'
I naturally get both the GET and the POST in API Bar, since only the path is referenced, not the method.
I tried this:
openapi: 3.0.0
info:
version: '1'
title: Bar
paths:
/foo:
get:
$ref: 'foo.yaml#/paths/~1foo/get'
But this gives errors like should NOT have additional properties additionalProperty: $ref and should have required property 'responses' missingProperty: responses in various tools, so it doesn't seem to be supported.
Is there a way to accomplish this? I should note that the real request is much more complicated, hence the desire to de-duplicate. If possible I would like to avoid filling in many child objects of get with individual $refs.
OpenAPI doesn't have a way to $ref an individual operation (get/post/etc.), you can only $ref an entire path.
You can propose syntax enhancements in the OpenAPI Specification repository:
https://github.com/OAI/OpenAPI-Specification/issues
I am trying to generate a project via JHipster with the OpenAPI option specified.
Create an OpenAPI specification file to define the entities and paths defining the application.
Create a JHipster .jdl file to specify the JHipster project parameters.
There are no entity definitions - this is intended to be provided by the OpenAPI file.
Execute JHipster (> jhipster import-jdl <file>.jdl).
Copy my OpenAPI file into src/main/resources/swagger/api.yml.
Execute OpenAPI sub-generator (> mvnw generate-sources).
This generates a microservice project, including the relevant OpenAPI classes generated by the OpenAPI sub-generator.
One very noticeable thing is missing: There is no code that deals with object persistence.
What do I need to do to provide this capability?
I know that JHipster has an entity sub-generator (entities can be defined in the JDL as well). This will generate a slew of code related to the defined entities, including persistence logic. However, this doesn't seem to fit well with the idea of defining entities in the OpenAPI specification file. I can't conceive of how these two techniques could possibly work together.
Has anyone done this?
Here are the relevant files for the curious:
[This is obviously an extremely simplistic application and persisting anything really makes little sense, but I'm providing it for illustration.]
jhipster.jdl:
application {
config {
packageName com.example
baseName echoMicroservice
applicationType microservice
serverPort 9100
buildTool maven
authenticationType jwt
clientPackageManager npm
serviceDiscoveryType no
messageBroker false
searchEngine false
databaseType sql
devDatabaseType mysql
prodDatabaseType mysql
cacheProvider hazelcast
enableHibernateCache false
clientFramework angularX
enableSwaggerCodegen true
}
}
echo-api.yml:
openapi: '3.0.1'
info:
title: 'echoMicroservice'
version: 0.0.1
servers:
- url: http://localhost:9100
description: Development server
- url: https://localhost:9100
description: Development server with TLS Profile
paths:
/random:
get:
summary: Returns a random message
description: Returns a random message
responses:
'200':
description: Random response
content:
application/json:
schema:
$ref: '#/components/schemas/Echo'
/echo:
post:
summary: Echoes a specified message
description: Echoes a specified message
requestBody:
description: Echo request
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Echo'
responses:
'200':
description: Echo response
content:
application/json:
schema:
$ref: '#/components/schemas/Echo'
components:
schemas:
Echo:
type: object
properties:
message:
type: string
I have a SOAP API already defined via WSDLs. Is there any tool that I can use to convert WSDL to Open API Swagger documents?
I am assuming that I would need to write custom code to to create a Swagger 3.0 Open API YAML specification from an XML.
XML:
<country>
<name>ABC</name>
<population>100</population>
<political_system>
<system_type>Democracy</system_type>
<legislature>bicameral</legislature>
</country>
Open API Definition:
openapi: "3.0.0"
info:
version: 1.0.0
title: SysCountry
servers:
- url: http://localhost:5595/api/
paths:
/Country:
get:
tags:
-countries
responses:
'200':
description:List of countries
content:
application/json:
schema:
$ref:"#/components/schemas/Countries
post:
summary:Create a country
tags:
-Conuntries
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Country'
responses:
'201':
description: Null response
components:
schemas:
Country:
type: object
required:
- name
properties:
name:
type: string
population:
type: integer
political_system:
type: object
properties:
system_type:
type: string
legislature:
type:string
Countries:
type: array
items:
$ref: "#/components/schemas/Country"
Is there any .NET C# library that can be used to create YAML documents programmatically (maybe something similar to an XMLDocument)?
I know this is an old question, but, I was looking for the same thing and couldn't find a decent, hassle free solution, so maybe this answer can help someone else too.
The easiest way I have found to convert a WSDL to YAML is using APIMATIC (www.apimatic.io).
A free account can convert as many WSDLs (or other formats) as you want, there's no need for a subscription.
Cheers.
There's YamlDotNet - https://github.com/aaubry/YamlDotNet
You can create a YamlStream + YamlDocument and build your document from there, similar to using XmlDocument.
Another approach is to create classes to represent the swagger document and use the serialization API to generate the document, similar to using XmlSerializer.