Skip to content
This repository has been archived by the owner on Aug 18, 2023. It is now read-only.

six (6) attempts to get YAML (**NOT** JSON) APIs to display in redocly developer portal. #114

Open
WaterSibilantFalling opened this issue Aug 5, 2021 · 10 comments
Open

six (6) attempts to get YAML (**NOT** JSON) APIs to display in redocly developer portal. #114

WaterSibilantFalling opened this issue Aug 5, 2021 · 10 comments

Comments

@WaterSibilantFalling
Copy link

These APIs are YAML NOT JSON. These YAML API path and schema fragments were created by redocly's create-openapi-repo tool

As instructed by Redocly, these fragments are place in directories under the openapi directory:

developer-portal
      openapi
             schema
              paths
                   Abcdefg
                    Banana
                    Frog

Attempt 1

The .....page.yaml file in the openapi/ dir
path files, like v1@Abcdefg({key})@products({relatedKey})@$ref.yaml in the
openapi/path/Abcdefg/ directory

in sidebar.yaml

  - group: MOA APIs
    expanded: true
    pages:
      - group: Abcdefg
        expanded: true
        pages:
          - page: "moa_Abcdefg.page.yaml/*"

Error

No "Error" messages, but didn't work

Attempt 2: The same, but with each of

	- page: "openapi/moa_Abcdefg.page.yaml"
	- page: "openapi/moa_Abcdefg.page.yaml/*"
	- page: "openapi/moa_Abcdefg.page.yaml/"
	- page: openapi/moa_Abcdefg.page.yaml
	- page: openapi/moa_Abcdefg.page.yaml/
	- page: openapi/moa_Abcdefg.page.yaml/*

Of course, none of these worked.

Note that the last of these, which DEFINITELY does not exist, does not give an error.
Those that DO exist, DO give errors

Errors about "File not found" only appear for files that EXIST.
When a file does NOT exist, no error.

Attempt 3

Directly listed each API file.

    pages:
      - group: Abcdefg
        expanded: true
        pages:
          - page: "openapi/paths/Abcdefg/moa_Abcdefg.page.yaml"
          - page: "openapi/paths/Abcdefg/v1@Abcdefg({key})@Products@$ref.yaml"
          - page: "openapi/paths/Abcdefg/v1@Abcdefg({key})@Products({relatedKey})@$ref.yaml"
          - page: "openapi/paths/Abcdefg/v1@Abcdefg({key})@SubCategories@$ref.yaml"
          - page: "openapi/paths/Abcdefg/v1@Abcdefg({key})@SubCategories({relatedKey}) @$ref.yaml"
          - page: "openapi/paths/Abcdefg/v1@Abcdefg({key}).yaml"
          - page: "openapi/paths/Abcdefg/[email protected]"

errors

Lots of (incorrect) errors about "could not find page"

Page "openapi/paths/Abcdefg/moa_Abcdefg.page.yaml" is not found. Verify path in "sidebars.yaml"

 ERROR
Could not find page: openapi/paths/Abcdefg/v1@Abcdefg({key})@Products@$ref.yaml.

 ERROR
Could not find page: openapi/paths/Abcdefg/v1@Abcdefg({key})@Products({relatedKey})@$ref.yaml.

Attempt 4

Based on the openapi directory. Not suprised that this didn't work - after all, nothing worked - but for completeness

  - group: MOA APIs
    expanded: true
    pages:
      - group: Abcdefg
        expanded: true
        pages:
          - page: "paths/Abcdefg/moa_Abcdefg.page.yaml"
          - page: "paths/Abcdefg/v1@Abcdefg({key})@Products@$ref.yaml"
          - page: "paths/Abcdefg/v1@Abcdefg({key})@Products({relatedKey})@$ref.yaml"
          - page: "paths/Abcdefg/v1@Abcdefg({key})@SubCategories@$ref.yaml"
          - page: "paths/Abcdefg/v1@Abcdefg({key})@SubCategories({relatedKey})@$ref.yaml"
          - page: "paths/Abcdefg/v1@Abcdefg({key}).yaml"
          - page: "paths/Abcdefg/[email protected]"

error


 ERROR
Page "paths/Abcdefg/moa_Abcdefg.page.yaml" is not found. Verify path in "sidebars.yaml"

 ERROR
Could not find page: paths/Abcdefg/v1@Abcdefg({key})@Products@$ref.yaml.

 ERROR
Could not find page: paths/Abcdefg/v1@Abcdefg({key})@Products({relatedKey})@$ref.yaml.

 ERROR
Could not find page: paths/Abcdefg/v1@Abcdefg({key})@SubCategories@$ref.yaml.

Attempt 5

Put the .....page.yaml file in the same directory as the 'path' files that describe the API. This is like the APIs represented in monolithic JSON (in the openapi dir) being in the same dir as the API path file.

  - group: MOA APIs
    expanded: true
    pages:
      - group: Abcdefg
        expanded: true
        pages:
          - page: "openapi/paths/Abcdefg/moa_Abcdefg.page.yaml/*"

error: No error, but no APIs displayed

Attempt 6

Put the path files in the opeanapi directory, like the JSON api file (that actually works).

      - group: Abcdefg
        expanded: true
        pages:
          - page: "moa_Abcdefg.page.yaml/*"
          - page: "v1@Abcdefg({key})@Products@$ref.yaml"
          - page: "v1@Abcdefg({key})@Products({relatedKey})@$ref.yaml"
          - page: "v1@Abcdefg({key})@SubCategories@$ref.yaml"
          - page: "v1@Abcdefg({key})@SubCategories({relatedKey})@$ref.yaml"
          - page: "v1@Abcdefg({key}).yaml"
          - page: "[email protected]"

Errors

Incorrect error messages saying "Could not find page".

 ERROR
Could not find page: v1@Abcdefg({key})@Products@$ref.yaml.

 ERROR
Could not find page: v1@Abcdefg({key})@Products({relatedKey})@$ref.yaml.

 ERROR
Could not find page: v1@Abcdefg({key})@SubCategories@$ref.yaml.
@adamaltman
Copy link
Member

Hi @WaterSibilantFalling can you please share your siteConfig.yaml contents, and the contents of one of your moa_Abcdefg.page.yaml file?

@WaterSibilantFalling
Copy link
Author

I think they're both default, as supplied.

siteConfig.yaml

meta:
  title: Plexure API Portal
  description: The one-stop-shop for Plexure API documentation
  siteUrl: https://portal-demo.redoc.ly
logo: ./images/logo.png
enableToc: true
oasDefinitions:
  userAuthorization: ./openapi/user-authorization.json
  anotherApi: ./openapi/another-api.json
  moaapis: ./openapi/moa_openapi.json
  # MUST be relative paths
  # add links to definitions in our API registry by using a fully qualified URL.
stylesheets:
  - https://fonts.googleapis.com/css?family=Roboto:300,400,600,700
  - https://fonts.googleapis.com/css?family=Source+Sans+Pro:300,400,600,700&display=swap
#ga:
  # you can use any options here from https://www.gatsbyjs.org/packages/gatsby-plugin-google-analytics/
  # note that GA doesn't work in DEV
#  trackingId: UA-45997213-1
#scripts:
#  - ./static/intercom.js
nav:

  - label: Plexure Repos
    icon: ./images/redocly-icon-white.png
    href: https://dev.azure.com/vmob/New%20Plexure/_git/vmob-backend/

  - search: true

footer:
  copyrightText: Copyright © Redocly 2019-2020. All right reserved.

moa_Abcdef.page.yaml file

type: reference-docs
definitionId: moaapis
showInfo: false
expand: true
label: Test Label in openapi.page.yaml
settings:
  corsProxyUrl: 'https://cors.redoc.ly' # todo use proper proxying instead of this hackaround
  generateCodeSamples:
    languages:
      - lang: curl
      - lang: JavaScript
      - lang: Node.js

@adamaltman
Copy link
Member

Is this moa_openapi.json file JSON or YAML:

moaapis: ./openapi/moa_openapi.json

Have you tried to put that file directly into our API registry?

@WaterSibilantFalling
Copy link
Author

WaterSibilantFalling commented Aug 7, 2021 •
edited
Loading

moa_openapi.json

That's a JSON file

When the openapi.yaml file (created by Redocly's create-openapi-repo tool) is used, that file is rejected by Redocly's developer-portal

yarn start    (actually `yarn run start | ansi2txt | col -b | tee logfile.log` because you don't have logging)

yarn run v1.22.10
$ redocly-portal develop -p 3999
info Images optimization disabled in dev mode, use --with-images-optimization to
 enable

info starting Redocly Portal development server

success open and validate gatsby-configs - 0.471s

success load plugins - 3.711s

     :
     : 

info Validated /bench/everything/aa___CURRENT/plexure/work/redocly/px_api_2/open
api/moa_api.yaml ====================

 ERROR

Errors encountered while bundling /bench/everything/aa___CURRENT/plexure/work/re
docly/px_api_2/openapi/moa_api.yaml

 ERROR

OpenAPI Definition error "openapi/moa_api.yaml":
This doesn’t look like an OpenAPI document.

Error: This doesn’t look like an OpenAPI document.

    at Object.detectOpenAPI (/bench/everything/aa___CURRENT/plexure/work/redocly
/px_api_2/node_modules/@redocly/openapi-core/lib/oas-types.js:20:15)
    at /bench/everything/aa___CURRENT/plexure/work/redocly/px_api_2/node_modules
/@redocly/openapi-core/lib/bundle.js:49:40
    at Generator.next (<anonymous>)
    at /bench/everything/aa___CURRENT/plexure/work/redocly/px_api_2/node_modu
           : 
           :

I think it's choking on the 'path' objects in the openapi.yaml file

@adamaltman
Copy link
Member

When the openapi.yaml file (created by Redocly's create-openapi-repo tool) is used, that file is rejected by Redocly's developer-portal

Don't use that create-openapi-repo tool, please. That tool was replaced by our openapi-cli tool. Assuming you want to split it, check the openapi-cli split command. If you don't want to split it, you can just put the raw file; however, you should make sure we consider it valid by running the openapi-cli tool lint command on it.

@WaterSibilantFalling
Copy link
Author

WaterSibilantFalling commented Aug 7, 2021 •
edited
Loading

Have you tried to put that file directly into our API registry?

No, and I don't currently intend to.

@adamaltman
Copy link
Member

There is no point for you in using our Developer portal. It requires a license.

@WaterSibilantFalling
Copy link
Author

WaterSibilantFalling commented Aug 8, 2021 •
edited
Loading

I have a licence. Oh, Is that it? Makes sense.

I have a license - Plexure paid for "premium"? is it? -
but I thought that what I did locally didn't require a license.

OK, I'll add the license key and retry.

Can you paste the link to the doc where is says that I need the license key to work on the developer portal locally, on this machine?

Is it this:
In https://redoc.ly/docs/api-reference-docs/on-premise/

To start using Redocly API reference docs on-premise, you need to have a license key.

@WaterSibilantFalling
Copy link
Author

WaterSibilantFalling commented Aug 8, 2021 •
edited
Loading

Don't use that create-openapi-repo tool, please. That tool was replaced by our openapi-cli tool. Assuming you want to split it, check the openapi-cli split command. If you don't want to split it, you can just put the raw file; however, you should make sure we consider it valid by running the openapi-cli tool lint command on it.

Oh, ok.

I didn't realise that one had replaced the other. I just thought they were two tools.

openapi-cli split

Oh, ok.. Will do.

@WaterSibilantFalling

This comment has been minimized.

Sign in to view
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@adamaltman @WaterSibilantFalling