I downloaded sample server program from http://editor.swagger.io. (Swagger Petstore (Simple), NodeJS)
Then I deployed into my server but the path is showed "Default". How can I change it?
This sample shows the name of paths. This is what I want to do it. http://petstore.swagger.io/#/
package.json
"dependencies": {
"connect": "^3.2.0",
"js-yaml": "^3.3.0",
"swagger-tools": "0.9.*"
}
=============================
Update
This may be related. How to change Swagger-UI "Default" Path
I'm not sure how JSON file is necessary. I'm using yaml. I may be choose .json or .yaml.
And also I'm wondering this is related to my issue..
{
schemaValidationMessages: [
{
level: "error",
message: "Can't read from file http://xxxxx/api-docs"
}
]
}
The grouping is done by the use of tags. Just tag each operation with a string array like such:
get:
tags:
- Admin Operations
parameters: []
The description for tags is defined in a top-level tags object:
tags:
- name: Admin Functions
description: These are only for special users!
And this will show the description in the top-level
Related
What I'm trying
I'm implementing a DELETE route using NestJS.
Since the route is only ever supposed to return a HTTP 204 No Content on successful deletion, utilizing the #nestjs/swagger decorators, I've annotated it as follows:
#ApiParam({
name: 'id',
required: true,
type: 'string',
example: 'abc123',
})
#ApiNoContentResponse({
description: 'All items for the given id have been deleted',
})
#Delete('/accounts/:id/items')
async deleteItems(
#Param('id') id: string,
) {
// do stuff
}
Stack
#nestjs/cli: 9.1.6
#nestjs/common: 9.1.6
#nestjs/core: 9.1.6
#nestjs/platform-express: 9.1.6
#nestjs/swagger: 6.1.2
nest-cli.json
{
"$schema": "https://json.schemastore.org/nest-cli",
"collection": "#nestjs/schematics",
"sourceRoot": "src",
"compilerOptions": {
"plugins": [
"#nestjs/swagger/plugin"
]
}
}
Question
How can I prevent this (default?) response from being generated?
What happens
When running the server with npm run start:dev, the swagger description for my route is created. Although I've not explicitly defined it, the description now contains an entry for HTTP 200 in the Response section of the route. The entry contains no description and no indicator that it's not explicitly defined.
What I expected to happen
When running the server with npm run start:dev, the swagger description for my route is created. The description only contains and entry for HTTP 204 in the Response section of the route.
What I've tried
Explicitly defined an #ApiOkResponse:
// they all have no effect
#ApiOkResponse()
// OR
#ApiOkResponse({})
// OR
#ApiOkResponse({ status: 204 })
Defined an #ApiDefaultResponse:
// they all create a response 'default' with no description
#ApiDefaultResponse()
// OR
#ApiDefaultResponse({})
// OR
#ApiDefaultResponse({ status: 204 })
You can just add #HttpCode(204) as an annotation to your code. 200 is added by default, because this is the default response status code for DELETE requests.This default behavior would be overwritten with the annotation mentioned above.
More information about the status codes can be found here: https://docs.nestjs.com/controllers
I try to organize my one giant OpenAPI yaml file into several small pieces and then bundle it with swagger-cli. And I run into the paths section.
This is my openapi.yml file now:
openapi: "3.0.0"
info:
version: 1.0.0
title: Swagger Petstore
description: Multi-file boilerplate for OpenAPI Specification.
license:
name: MIT
servers:
- url: http://example.swagger.io/v1
paths:
/blog:
$ref: './routes/blog/create-getall.yml'
/blog/{id}:
$ref: './routes/blog/show-update-delete.yml'
Now the problem is I want to separate create-getall.yml file into create.yml and get-all.yml, and I want to split show-update-delete.yml file into show.yml, update.yml and delete.yml files.
But after I do this split, I try to use files as reference like this:
paths:
/blog:
$ref: './routes/blog/create.yml'
$ref: './routes/blog/get-all.yml'
/blog/{id}:
$ref: './routes/blog/with-id.yml'
And I get Map keys must be unique error message.
If I try $ref1, $ref2 and similar, then I get Property $ref1 is not allowed error.
I tried to use allOf, but it leads to Property allOf is not allowed. error.
The create.yml file is this:
post:
tags:
- blog
summary: create a blog post
description: |
You can create a new blog post.
parameters:
- in: body
name: content
schema:
$ref: 'Post.yml'
responses:
200:
description: new item's ID
So how can I use these splitted files in paths section?
OpenAPI Specification does not have a way to use multiple $refs under a single path. There's an existing feature request to allow $refs on the operation level which, if implemented, would support your scenario.
In Open Policy Agent (https://www.openpolicyagent.org/)
regarding to Kubernetes, depending which engine is used:
Gatekeeper: https://github.com/open-policy-agent/gatekeeper
OR
Plain OPA with kube-mgmt: https://www.openpolicyagent.org/docs/latest/kubernetes-introduction/#how-does-it-work-with-plain-opa-and-kube-mgmt
There are different ways to define validation rules:
In Gatekeeper the violation is used. See sample rules here: https://github.com/open-policy-agent/gatekeeper-library/tree/master/library/general
In plain OPA samples, the deny rule, see sample here:
https://www.openpolicyagent.org/docs/latest/kubernetes-introduction/#how-does-it-work-with-plain-opa-and-kube-mgmt
It seems to be the OPA constraint framework defines it as violation:
https://github.com/open-policy-agent/frameworks/tree/master/constraint#rule-schema
So what is the exact "story" behind this, why it is not consistent between the different engines?
Notes:
This doc reflects on this: https://www.openshift.com/blog/better-kubernetes-security-with-open-policy-agent-opa-part-2
Here is mentioned how to support interoperability in the script: https://github.com/open-policy-agent/gatekeeper/issues/1168#issuecomment-794759747
https://github.com/open-policy-agent/gatekeeper/issues/168 In this issue is the migration mentioned, is just because of "dry run" support?.
Plain OPA has no opinion on how you choose to name your rules. Using deny is just a convention in the tutorial. The real Kubernetes admission review response is going to look something like this:
{
"kind": "AdmissionReview",
"apiVersion": "admission.k8s.io/v1beta1",
"response": {
"allowed": false,
"status": {
"reason": "container image refers to illegal registry (must be hooli.com)"
}
}
}
So whatever you choose to name your rules the response will need to be transformed into a response like the above before it's sent back to the Kubernetes API server. If you scroll down a bit in the Detailed Admission Control Flow section of the Kubernetes primer docs, you'll see how this transformation is accomplished in the system.main rule:
package system
import data.kubernetes.admission
main = {
"apiVersion": "admission.k8s.io/v1beta1",
"kind": "AdmissionReview",
"response": response,
}
default response = {"allowed": true}
response = {
"allowed": false,
"status": {
"reason": reason,
},
} {
reason = concat(", ", admission.deny)
reason != ""
}
Note in particular how the "reason" attribute is just built by concatenating all the strings found in admission.deny:
reason = concat(", ", admission.deny)
If you'd rather use violation or some other rule name using plain OPA, this is where you would change it.
How to specify a property as null or a reference? discusses how to specify a property as null or a reference using jsonschema.
I'm looking to do the same thing with swagger.
To recap the answer to the above, with jsonschema, one could do this:
{
"definitions": {
"Foo": {
# some complex object
}
},
"type": "object",
"properties": {
"foo": {
"oneOf": [
{"$ref": "#/definitions/Foo"},
{"type": "null"}
]
}
}
}
The key point to the answer was the use of oneOf.
The key points to my question:
I have a complex object which I want to keep DRY so I put it in a
definitions section for reuse throughout my swagger spec: values of other properties; response objects, etc.
In various places in my spec a
property may be a reference to such an object OR be null.
How do I specify this with Swagger which doesn't support oneOf or
anyOf?
Note: some swagger implementations use x-nullable (or some-such) to specify a property value can be null, however, $ref replaces the object with what it references, so it would appear any use of x-nullable is ignored.
OpenAPI 3.1
Define the property as anyOf of the $ref and type: 'null'.
YAML version:
foo:
anyOf:
- type: 'null' # Note the quotes around 'null'
- $ref: '#/components/schemas/Foo'
JSON version:
"foo": {
"anyOf": [
{ "type": "null" },
{ "$ref": "#/components/schemas/Foo" }
]
}
Why use anyOf and not oneOf? oneOf will fail validation if the referenced schema itself allows nulls, whereas anyOf will work.
OpenAPI 3.0
YAML version:
foo:
nullable: true
allOf:
- $ref: '#/components/schemas/Foo'
JSON version:
"foo": {
"nullable": true,
"allOf": [
{ "$ref": "#/components/schemas/Foo" }
]
}
In OAS 3.0, wrapping $ref into allOf is needed to combine the $ref with other keywords - because $ref overwrites any sibling keywords. This is further discussed in the OpenAPI Specification repository: Reference objects don't combine well with “nullable”
Not easy to do that. Even almost impossible. Your options :
Wait
There is a very long discussion about this point, maybe one day it will be done...
Use vendors extensions
You can use vendors extensions like x-oneOf and x-anyOf. I have already taken this hard way: You must to upgrade all used 'swagger tools' to take into account these vendors extensions.
In my case, we needed 'only' to :
Develops our own Jax-RS parser with customized annotations in order to extract swagger API file from sources
Extends swagger-codegen to take into account these extensions to generate java code for our clients
Develops our own swagger-ui: to facilitate this work, we added a preprocessing step to convert our swagger schema with our extensions to a valid json schema. It's easier to find a module to represent json schemas than swagger schemas in javascript. By cons we gave up the idea to test the API with the 'try it' button.
It was a year ago, maybe now ...
Refactor your APIs
Many projects don't need anyOf and oneOf, why not us ?
For OpenAPI 3.0 for some reason using nullable: true followed by allOf didn't work for the OpenAPI interpreter I'm using. As a workaround I ended up defining a must-be-null ref called null_type that I can use in an anyOf construct.
Like so:
allOf:
- anyOf:
- $ref: "#/components/schemas/null_type"
- $ref: "#/components/schemas/your_ref"
- description: "optionally add other properties here..."
where:
schemas:
null_type:
title: "OpenAPI 3.0 null-type ref"
description: "for adding nullability to a ref"
enum: [null]
your_ref:
...
In my swagger file I have defined a list of tags as follows:
"tags": [
{ "name": "TagA", "description": "DescriptionA" },
{ "name": "TagB", "description": "DescriptionB" }
]
When I generate client code using swagger-codegen (2.1.2-M1), all operations marked with a certain tag become methods in a class named after the tag, e.g. "class TagBApi". Is there any way to retrieve the tag description and output it as a comment in the class? I haven't seen any examples of this in the available .mustache files. Thanks.
there is no support for the tag descriptions in the codegen--please open an issue and it can be added.