0

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":
B Ahern
  • 11
  • 4
  • This is a valid root structure. But it looks like you reference it from some different place. You reference root OpenAPI document in the place where Path Object is expected. – RomanHotsiy Dec 14 '22 at 03:54
  • @RomanHotsiy is it possible for you to go into more detail? Im just having trouble interpreting it. Is there any more code I can add to help? – B Ahern Dec 14 '22 at 13:14
  • @BAhern it sounds like your Root file may not be a root file and it looks like your PathItem file is not a PathItem. You could help by pasting contents of both files into your question. As it is, not enough information to provide clear help. – Domino Dec 14 '22 at 13:29
  • @Domino i added more lines from root file and path item file. The path item file is around 1500 lines so just added the first 60. Let me know if this is optimal – B Ahern Dec 14 '22 at 14:20

0 Answers0