I'm using Swagger YAML file for producing interactive documentation on apiary.io.
I've noticed a strange issue where if I specify a default value 0 for an integer, the interactive documentation doesn't render it at all and shows "null" as default value instead. If i specify a non-zero value it renders perfectly fine.
Example :
- name: pageNumber
in: query
description: The page number, starting at 0.
required: true
type: number
format: int32
default: 0
- name: pageSize
in: query
description: The page size (max number of entities that are displayed in the
response).
required: true
type: integer
format: int32
default: 20
Appends ?pageNumber=&pageSize=20 to my path whereas it should've added ?pageNumber=0&pageSize=20 instead.
When I add a non-zero as follows :
- name: pageNumber
in: query
description: The page number, starting at 0.
required: true
type: number
format: int32
default: 1
- name: pageSize
in: query
description: The page size (max number of entities that are displayed in the
response).
required: true
type: integer
format: int32
default: 20
This is rendered fine, and appends ?pageNumber=1&pageSize=20 as expected.
Helen's comment resolved my issue.
When documenting using YAML on apiary.io, for setting default/initial values in the interactive documentation, x-example needs to be used. Now, the following works as expected :
- name: pageNumber
in: query
description: The page number, starting at 0.
required: true
type: number
format: int32
x-example: 0
- name: pageSize
in: query
description: The page size (max number of entities that are displayed in the
response).
required: true
type: integer
format: int32
x-example: 20
Successfully gets rendered as ?pageNumber=0&pageSize=20
Related
Can I validate both
name: "range_1"
step: 1
start: 0
stop: 10
and
name: "range_2"
step: 1
center: 5
span: 5
with something like
properties:
name:
type: "string"
stop:
type: number
oneOf:
- start:
type: number
step:
type: number
- center:
type: number
span:
type: number
For now I am using jsonschema in Python, but it complains jsonschema.exceptions.SchemaError: <the array in oneOf> is not of type 'object', 'boolean'.
Validating against name and step only or validating against all possible keys apparently works but they both seem sub-optimal for me.
You need to move the oneOf keyword out of the properties object as everything in the properties object is interpreted as an expected value in your data.
Additionally, it makes sense to add an required property to make the values mandatory. Finally, if you want to make sure that no other values are excepted, you can use additionalProperties: false. Note though, that you have to repeat the "parent" properties in the oneOf schemas again. For further reading I recommend this example.
Put all together, you could use the following schema (see live example here):
---
properties:
name:
type: string
step:
type: number
oneOf:
- properties:
name: true
step: true
start:
type: number
stop:
type: number
required:
- start
- stop
additionalProperties: false
- properties:
name: true
step: true
center:
type: number
span:
type: number
required:
- center
- span
additionalProperties: false
I am trying to create an api documentation using redocly.
On my openapi.yaml it is linking to a yaml that has the api docs called kpi-documentation.yaml
link/$ref in openapi.yaml
/kpiDocumentation:
$ref: paths/kpi-documentation.yaml
I have an error in my visual studio code redocly preview extension that says
We found structural problems in your definition, please check the files below before running the preview.
File: /Users/xx/Desktop/Projects/api-docs/openapi/paths/kpi-documentation.yaml
Problem: Property `openapi` is not expected here.
File: /Users/xx/Desktop/Projects/api-docs/openapi/paths/kpi-documentation.yaml
Problem: Property `info` is not expected here.
File: /Users/xx/Desktop/Projects/api-docs/openapi/paths/kpi-documentation.yaml
Problem: Property `paths` is not expected here.
File: /Users/xx/Desktop/Projects/api-docs/openapi/paths/kpi-documentation.yaml
Problem: Property `components` is not expected here.
Part of code that I have in the kpi-documentation.yaml that appears to be throwing the error is
openapi: "3.1"
info:
title: KPI API
version: '1.0'
description: Documentation of API endpoints of KPI
servers:
- url: https://api.redocly.com
paths:
I have checked the documentation on the redocly website and it looks like my yaml structure is fine.
Also to note the kpi-documentation previews fine by itself when using the preview, but not when I preview the openapi.yaml which is the root file that needs to work.
https://redocly.com/docs/openapi-visual-reference/openapi/#OAS-3.0
rootfile
openapi.yaml
openapi: 3.1.0
info:
version: 1.0.0
title: KPI API documentation
termsOfService: 'https://example.com/terms/'
contact:
name: Brendan
url: 'http://example.com/contact'
license:
name: Apache 2.0
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
x-logo:
url: 'https://www.feedgy.solar/wp-content/uploads/2022/07/Sans-titre-1.png'
tags:
- name: Insert Service 1
description: Example echo operations.
- name: Insert Service 2
description: Operations about users.
- name: Insert Service 3
description: This is a tag description.
- name: Insert Service 4
description: This is a tag description.
servers:
- url: 'https://{tenant}/api/v1'
variables:
tenant:
default: www
description: Your tenant id
- url: 'https://example.com/api/v1'
paths:
'/users/{username}':
$ref: 'paths/users_{username}.yaml'
/echo:
$ref: paths/echo.yaml
/pathItem:
$ref: paths/path-item.yaml
/pathItemWithExamples:
$ref: paths/path-item-with-examples.yaml
/kpiDocumentation:
$ref: 'paths/kpi-documentation.yaml'
pathitem file
kpi-documentation.yaml
openapi: "3.1"
info:
title: KPI API
version: '1.0'
description: Documentation of API endpoints of KPI
servers:
- url: https://api.redocly.com
paths:
"/api/v1/corrected-performance-ratio/plants/{id}":
get:
summary: Same as the Performance Ratio, but the ratio is done using Corrected Reference Yield, so it considers thermal losses in the panels as normal. The WCPR represents the losses in the BoS (balance of system), so everything from the panel DC output to the AC output.
operationId: corrected_performance_ratio_plants_retrieve
parameters:
- in: query
name: date_end
schema:
type: string
format: date
required: true
- in: query
name: date_start
schema:
type: string
format: date
required: true
- in: query
name: frequency
schema:
enum:
- H
- D
- M
- Y
type: string
default: H
minLength: 1
- in: path
name: id
schema:
type: integer
description: A unique integer value identifying this plant.
required: true
- in: query
name: threshold
schema:
type: integer
default: 50
tags:
- corrected-performance-ratio
security:
- tokenAuth: []
- cookieAuth: []
- {}
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/KPIResponse"
description: ""
"/api/v1/corrected-performance-ratio/plants/{id}/inverters":
I have a swagger.yaml file having a lot of APIs. I would like to remove all the parameters with the name of user-id from all of the APIs. Also, there are examples and x-examples which are irrelevant for my use-case that I would like to be removed.
I have been experimenting with openapi-filter. However, for it to work I'll have to add a special tag to the parameters and it won't work for examples. I could also be using it incorrectly.
parameters:
- name: action-id
in: path
description: Action ID which needs to be failed
required: true
type: integer
format: int64
x-example: 1
- name: action-category-number
in: path
description: Action category number which needs to be failed
required: true
type: integer
format: int64
example: 2
- name: user-id
in: header
description: User under which the action exists
required: true
type: integer
format: int32
x-example: 1
Expected output:
parameters:
- name: action-id
in: path
description: Action ID which needs to be failed
required: true
type: integer
format: int64
- name: action-category-number
in: path
description: Action category number which needs to be failed
required: true
type: integer
format: int64
This question already has answers here:
Swagger: How to have a property reference a model in OpenAPI 2.0 (i.e. nest the models)?
(2 answers)
Closed 2 years ago.
I created a definition called Product and another called Text (see code).
On parameters of paths I can not use the type Text created in definitions. On the definition Product I have a property called message and I want that property to be the type Text too.
(...)
paths:
/products:
get:
summary: Product Types
description: |
Description text
parameters:
- name: latitude
in: query
description: Latitude component of location.
required: true
### The type Text was not found here
type: Text ### The type Text was not found here
(...)
definitions:
Product:
properties:
message:
### The type Text was not found here
type: Text ### Compilation Error in this line ####
name:
type: string
description: Data description.
Text:
properties:
code:
type: string
But this error occurs:
Swagger Error:
Data does not match any schemas from 'anyOf'.
How can I reference the type Text on the type Product?
Please use $ref instead. Here is an example
type: object
required:
- name
properties:
name:
type: string
address:
$ref: '#/definitions/Address'
age:
type: integer
format: int32
minimum: 0
Ref: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#simple-model
In Symfony2, you can translate your validation error messages:
Validation File
# src/Acme/BlogBundle/Resources/config/validation.yml
Acme\BlogBundle\Entity\Author:
properties:
name:
- NotBlank: { message: "author.name.not_blank" }
Translation File
# validators.en.yml
author.name.not_blank: Please enter an author name.
But how can I pass a parameter to the translation file, if e.g. I want to pass the required min or max length?
author.name.min_length: "Required length: %limit% characters."
What about,
Acme\BlogBundle\Entity\Author:
properties:
name:
- NotBlank: { message: "author.name.not_blank" }
- Length:
min: 3
minMessage: "author.name.min_length"
While your translation file should contain,
# validators.en.yml
author.name.not_blank: Please enter an author name.
author.name.min_length: "Required length: {{ limit }} characters."
The {{ limit }} placeholder here will then fit the min pamarater of the length constraint.