This is the description of a certain parameter I have:
{
"name": "myParam",
"description": "My param description",
"required": true,
"paramType": "query",
"type": "string",
"defaultValue":"myValue"
}
The defaultValue is the only value the parameter can have, so is there a way to declare this? Seen in the context of the swagger-ui, I need the parameter's textbox to be read-only. I'm using swagger 1.2.
Thanks
The proper way to declare this would be:
{
"name": "myParam",
"description": "My param description",
"required": true,
"paramType": "query",
"type": "string",
"enum": [ "myValue" ]
}
The "enum" property sets the possible values. Once you set a single value to it, that's the only one that could be used and that would be available in the UI for the user to choose from.
I'm a bit late to the game but with OpenAPI 3.1 you can do the following:
defaultValue:
type: string
const:
- myValue
You can also use 'pattern' of the string to avoid the enum - this could look better in Swagger:
{
"openapi": "3.0.0",
"components": {
"schemas": {
"object": {
"type": "object",
"required": [
"myParam"
],
"properties": {
"myParam": {
"type": "string",
"pattern": "onlyAllowedValue$"
}
}
}
}
}
}
Related
I'm using swagger 2.0 and I have the following schema(definition) :
"User": {
"type": "object",
"properties": {
"firstName": {
"type": "string",
"example": "Tom"
},
"lastName": {
"type": "string",
"example": "Hanks"
},
"email": {
"type": "string",
"example": "Tom.Hanks#gmail.com"
},
"password": {
"type": "string",
"example": "azerty#123456"
}
}
and i want to refer to this schema in one of my responses, so i do the following:
"responses": {
"201": {
"description": "Created.",
"schema": {
"$ref": "#/definitions/User"
}
}
}
Until now everything works perfectly, but i don't want to expose the password property in the response schema. is the anyway to choose exactly the properties i want to use from the Userdefinition ?
No, there is no way. I'd suggest you define 2 types:
One type for user data without password, let's name it User.
And another type that inherits from it and contains additionally a password attribute. Let's name it UserWithCredential.
I have this definition in a swagger document:
"/myEndpoint": {
"post": {
"summary": "handle",
"operationId": "handleUsingGET",
"produces": ["application/json", "application/vnd.spring-boot.actuator.v2+json"],
"parameters": [{
"in": "body",
"name": "body",
"description": "body",
"required": false,
"schema": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
],
"responses": { ... }
}
I need to create a request with a body but I'm not sure how to do that with this schema definition. I have read this question so I know that additionalProperties is used to represent a Dictionary. But there is no property name or anything specified here, so can we say any key-value pairs would be valid to sent in the body? Or is this definition not complete?
I am using Swagger Editor to work on a JSON Swagger 2.0 API definition. I have reduced my definition to a minimum example of the problem I am experiencing. The problem occurs when I use a reference object to define a path parameter that is shared between multiple endpoints.
Example endpoints:
/my-api/{id}/some-thing
/my-api/{id}/some-other-thing
Since these id parameters are defined the same way, I abstracted them to the parameters section of the JSON file, and included them with "$ref": "#/parameters/testObjectId".
The Swagger reduced definition shows this:
{
"swagger": "2.0",
"info": {
"title": "Test Service",
"description": "REST API for TestObjects",
"version": "1.0.0"
},
"host": "api.not-a-real-url.com",
"schemes": [
"https"
],
"basePath": "/api/test-objects",
"produces": [
"application/hal+json"
],
"consumes": [
"application/json"
],
"paths": {
"/{id}": {
"get": {
"operationId": "getTestObject",
"summary": "Get a TestObject resource referenced by slug string ID",
"security": [],
"parameters": [
{
"$ref": "#/parameters/testObjectId"
}
],
"responses": {
"200": {
"description": "Success",
"schema": {
"type": "object",
"properties": {}
}
},
"default": {
"description": "Error",
"schema": {
"type": "object",
"properties": {}
}
}
}
}
}
},
"parameters": {
"testObjectId": {
"name": "id",
"in": "path",
"required": true,
"type": "string",
"format": "slug",
"description": "Immutable, unique identifier of a TestObject"
}
},
"definitions": {
}
}
But when this is rendered in Swagger, I get the following error:
Errors
Semantic error at paths./{id}
Declared path parameter "id" needs to be defined as a path parameter at either the path or operation level
The problem is that id is actually defined, only it appears that the check which throws this error is occurring before the $ref is included. The Swagger output looks correct.
Further, I have used this approach for about 6 months (as long as I have used Swagger) and I am just now running into the problem for the first time. Is there something I should be doing differently to prevent this error? Am I misusing Swagger by doing it this way?
Your spec is valid. It was a bug introduced in Swagger Editor v.3.2.2, it was fixed in v.3.2.3 (released on January 6, 2018).
Is it possible (and how) to specify additional parameters that depend on the value of another given parameter?
Example
I have a call PUT /accounts/<account_id>/payment_method which takes some parameters besides the path parameter.
One is payment_method_type which defines the payment method to be set.
Now: if payment_method_type is DD for direct debit, there are some more parameters allowed (and needed) like account_holder and iban.
If it is something else, e. g. PP, other parameters are needed.
Excerpt from the json
"parameters": {
"payment_method_type": {
"name": "type",
"description": "Payment method type.",
"in": "query",
"required": true,
"type": "string",
"enum": [
"DD", "IV", "PP"
]
},
"payment_method_data_dd_account_holder": {
"name": "account_holder",
"description": "Name of account holder",
"in": "query",
"required": false, # but true if payment_method_type == DD
"type": "string"
},
"payment_method_data_dd_iban": {
"name": "iban",
"description": "IBAN",
"in": "query",
"required": false, # but true if payment_method_type == DD
"type": "string"
},
"payment_method_data_pp_some_info": {
"name": "some_info",
"description": "Some info needed for PP",
"in": "query",
"required": false, # but true if payment_method_type == PP
"type": "string"
},
}
"paths": {
"/accounts/{account_id}/payment_method": {
"put": {
"summary": "Update Payment Method",
"description": "...",
"parameters": {
{
"$ref": "#/parameters/path_psp_account_id"
},
{
"$ref": "#/parameters/payment_method_type"
},
{
"$ref": "#/parameters/payment_method_data_dd_account_holder"
},
{
"$ref": "#/parameters/payment_method_data_dd_iban"
},
{
"$ref": "#/parameters/payment_method_data_pp_some_info"
},
}
}
}
}
I'd like to get rid of the long parameter list (since there are more parameters left out here) but group them as described above and document that some parameters are required (and allowed) only for special types.
Is there a way to describe this?
Is there a way to define sets of parameters like all the direct debit parameters in one definition and reference it? Remark: those parameters are given next to the payment_method_type parameter and not inside a sub-object.
There is no way to have conditional parameters in the current swagger specification.
Yes, the parameters array allows a $ref pointer.
Does anyone know how to define possible enum values in an OpenAPI 2.0 definition so that they will be displayed in the Model tab of Swagger UI? Example here has an enum option for the status property. How to do define such an enum in OpenAPI 2.0?
"enum" works like this in OpenAPI 2.0:
{
"in": "query",
"name": "sample",
"description": "a sample parameter with an enum value",
"type": "string",
"enum": [ "1", "2"],
"required": true
}
and in OpenAPI 3.0:
{
"in": "query",
"name": "sample",
"description": "a sample parameter with an enum value",
"schema": {
"type": "string",
"enum": [ "1", "2"]
},
"required": true
}
As you can see, there's a query parameter called sample of type string, and has an enum stating two possible values. In this case, the sample states the parameter is required, so the UI will not show an empty value as an option.
For a minimal working sample, try this:
{
"swagger": "2.0",
"info": {
"title": "title",
"description": "descriptor",
"version": "0.1"
},
"paths": {
"/sample": {
"post": {
"description": "sample",
"parameters": [
{
"in": "query",
"name": "sample",
"description": "a sample parameter with an enum value",
"type": "string",
"enum": [
"1",
"2"
],
"required": true
}
],
"responses": {
"200": {
"description": "Successful request."
}
}
}
}
}
}
To test it locally, you can declare a variable (for example spec) in your javascript, and pass it into the SwaggerUi object.
var spec = { ... };
window.swaggerUi = new SwaggerUi({
url: url,
spec: spec,
dom_id: "swagger-ui-container",
supportedSubmitMethods: ['get', 'post', 'put', 'delete'],
onComplete: function(swaggerApi, swaggerUi){
...
The url parameter will be ignored in this case.
Eventually, the output looks like this:
Updating this with YAML syntax.
OpenAPI 2.0:
parameters:
- in: query
name: sample
description: a sample parameter with an enum value
type: string
enum:
- 1
- 2
required: true
OpenAPI 3.0:
parameters:
- in: query
name: sample
description: a sample parameter with an enum value
schema:
type: string
enum:
- 1
- 2
required: true
This should work:
{
"name": "bookingType",
"in": "path",
"type": "array",
"items": {
"enum": [
"packages", "accommodations"
]
},
"description": "lorem ipsum"
}
Reference https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#itemsObject
This isn't the exact answer, but it might work for you until they add this functionality.
Simply declare the property like so
"MyObject":{
"properties":{
"MyEnum":{
"type":"Value1 or Value2 or Value3"
}
}
}
Your ModelSchema will show {}, but The Model will show MyEnum(Value1 or Value2 or Value3, optional)