Redocly OpenAPI structure error. Property `openapi` is not expected here - yaml

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":

Related

How to write a schema to constrain some of the properties with one/any of the sub-schemas?

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

Remove a specific parameter and examples from Swagger Doc

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

yq add property to object somewhere in the tree

I'm trying to add a response to all objects with the key responses in an open api yaml file. I tried a lot and failed hard because I think I miss some basic understanding but I don't know what exactly.
File
openapi: 3.0.1
info:
title: my service
description: API for my service
version: 1.0.0
security:
- jwt:
- read
paths:
'/foo/{fooId}/firmware/update-request':
post:
parameters:
- name: fooId
in: path
description: Foo Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FooRequest'
example:
firmwareVersion: "0.1"
responses:
'202':
description: Foo has been done
'400':
$ref: '#/components/responses/BadRequest'
'409':
$ref: '#/components/responses/Conflict'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
'502':
$ref: '#/components/responses/BadGateway'
'/foo/{fooId}/firmware/auto-update':
put:
parameters:
- name: fooId
in: path
description: Foo Id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FooUpdate'
example:
enabled: true
responses:
'204':
description: Foo update
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
'502':
$ref: '#/components/responses/BadGateway'
# goes on forever
Goal is that every response looks like
responses:
'204':
description: Foo update
# ...
'xxx':
description: yyy
while keeping the file structure intact.
What I tried:
yq -i '.. | select(has("responses")).responses | . += {"xxx": {"description": yyy}}' my.yaml
This was the idea, that came the closet my my expected result. But now every node from root to responses are missing.
What is the correct syntax to tell yq "Do this transformation in place on every node with this name without knowing it's level and without affecting every other node"?
You were almost there. Just wrap the whole search on the LHS into parentheses to eventually retain the outer context:
(.. | select(has("responses")).responses) += {"xxx": {"description": "yyy"}}
Note: I have also wrapped yyy in quotes and simplified | . += to just +=.
You could also just set the xxx field directly:
(.. | select(has("responses")).responses).xxx = {"description": "yyy"}
Both of these assume to be executed with mikefarah/yq. For a kislyuk/yq solution, add a ? to get has("responses")? as .. will also capture non-objects.
This was tested on mikefarah/yq version 4.20.2, and on kislyuk/yq version 3.0.2.

how to take duplicate configurations out in filebeat.yaml

I have a list of inputs in filebeat, for example
- path: /xxx/xx.log
enabled: true
type: log
fields:
topic: topic_1
- path: /xxx/ss.log
enabled: true
type: log
fields:
topic: topic_2
so can I take the duplicate configs out as a reference variable? for example
- path: /xxx/xx.log
${vars}
fields:
topic: topic_1
- path: /xxx/ss.log
${vars}
fields:
topic: topic_2
You can use YAML's inheritance : your first input is used as a model, and the others can override parameters.
- &default-log
path: /xxx/xx.log
enabled: true
type: log
fields:
topic: topic_1
- <<: *default-log
path: /xxx/ss.log
fields:
topic: topic_2
AFAIK there is no way to define an "abstract" default, meaning your &default-log should be one of your inputs (not just an abstract model).
(YAML syntax verified with YAMLlint)

inno ide component selected by types

Inno ide for example,
have two types which specifies some components but I don't want to list all components same list,
user select first type then i want only list first type's files and if select second type then I want only list second type's files.
[Types]
Name: "sunucu"; Description: "Sunucu Bileşenleri";Flags: iscustom
Name: "istemci"; Description: "İstemci Bileşenleri"
[Components]
Name: "readme"; Description: "Envanter Tanımlama Aracı"; Types: istemci
Name: "readme\de1"; Description: "Yetkili Kullanıcı"; Flags: exclusive; Types: istemci
Name: "readme\de2"; Description: "Genel Kullanıcı"; Flags: exclusive; Types: istemci
Name: "Jhe"; Description: "Jenerik Harita Editörü"; Types: istemci
Name: "Mim"; Description: "Model İşletim Motoru"; Types: sunucu
Name: "OSSB"; Description: "Ortam Şartları Sunucu Birimi"; Types: sunucu
Name: "SIM_ART_PACKAGE"; Description: "Simülasyon Analiz ve Raporlama Aracı"; Types: istemci
Name: "SIM_PACKAGE"; Description: "Simülasyon Arayüz Modülü"; Types: istemci
Name: "SPM"; Description: "Simülasyon Planlama Modülü"; Types: istemci
Name: "VTKB"; Description: "Simülasyon Kayıt Modülü"; Types: sunucu
Name: "VSMS"; Description: "Simülasyon Koşturma Servisi"; Types: sunucu
Name: "VSMS\s1"; Description: "SKS KAYIT"; Types: sunucu
Name: "VSMS\s2"; Description: "SKS"; Types: sunucu
Name: "VSMS\s3"; Description: "SKS OYNATMA"; Types: sunucu
Inno can not hide/show components based on the type selected, and [Types] are not designed to completely change how the install works.
If the two types are completely different with no overlap, you're best off doing two separate installs, or have a custom page before hand asking which mode you want to install into and useing a check: function to determine whether to show them or not.

Resources