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

WaterSibilantFalling commented 2 years ago

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/v1@Abcdefg.yaml"

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/v1@Abcdefg.yaml"

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: "v1@Abcdefg.yaml"

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 commented 2 years ago

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

WaterSibilantFalling commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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

No, and I don't currently intend to.

adamaltman commented 2 years ago

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

WaterSibilantFalling commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

EDIT: these could be to do with not using the license key. If so, maybe they should fail with an appropriate message.

EDIT: uninstalled and reinstalled @redocly/openapi-cli . . . and all then worked fine.

06:36 Sun 08-Aug-21 [/bench/current/plexure/work/redocly/px_api_2]
my_prompt > npx @redocly/openapi-cli split

Unknown command split       **<<---- this**

Usage: openapi [options] [command]

Options:
  -v, --version                        Output current version of the OpenAPI CLI.
  -h, --help                           display help for command

Commands:
  registry:login [options]             Login to the Redoc.ly API Registry with access token
  registry:logout                      Clear stored credentials for Redoc.ly API Registry
  bundle [options] [entryPoints...]    Create a bundle using <entryPoint> as a root document.
  validate [options] [entryPoints...]  Validate given OpenAPI 3 definition file.
  preview-docs [options] [entryPoint]  Preview API Reference docs for the specified entrypoint OAS definition
  help [command]                       display help for command

and if I give it a JSON openapi file to split. . . the same.

06:55 Sun 08-Aug-21 [/bench/current/plexure/work/redocly/px_api_2]
my_prompt > npx @redocly/openapi-cli split work/moa_openapi.json

Unknown command split work/moa_openapi.json

Usage: openapi [options] [command]

Options:

in yarn.lock:

"@redocly/developer-portal@1.0.0-beta.162":
  version "1.0.0-beta.162"
  resolved "https://registry.yarnpkg.com/@redocly/developer-portal/-/developer-portal-1.0.0-beta.162.tgz#ab4c0412867582fe312e7c3e9e2e0b35024cb087"
  integrity sha512-BIUAkzK2a7ZQnx1RELR8ic2olhO4FXYxGN3zh3Yn8APxHDd/s7Ra4UaU3Q0j0cPQupx1/TC5TcljnZYCldVSeg==
  dependencies:
    "@mdx-js/mdx" "0.19.0"
    "@mdx-js/tag" "0.20.3"
    "@redocly/gatsby-remark-images" "4.2.0"
    "@redocly/openapi-cli" "~0.12.1"
    "@redocly/reference-docs" "~1.5.13"
    babel-plugin-styled-components "^1.12.0"
    buffer "^6.0.3"
    chalk "^4.1.1"
    cheerio "^1.0.0-rc.9"
    core-js "^3.12.0"
    details-polyfill "^1.2.0"
    elasticlunr "0.9.5"
    gatsby "3.2.1"
    gatsby-cli "^3.5.0"
    gatsby-plugin-canonical-urls "3.2.0"
    gatsby-plugin-catch-links "3.2.0"
    gatsby-plugin-fullstory "~3.4.0"
    gatsby-plugin-google-analytics "3.2.0"
    gatsby-plugin-google-gtag "^3.5.0"
    gatsby-plugin-google-tagmanager "3.2.0"
    gatsby-plugin-heap "1.1.0"
    gatsby-plugin-layout "2.2.0"
    gatsby-plugin-manifest "3.2.0"
    gatsby-plugin-nprogress "3.2.0"
    gatsby-plugin-react-helmet "4.2.0"
    gatsby-plugin-segment-js "3.6.0"
    gatsby-plugin-sitemap "3.2.0"
    gatsby-plugin-styled-components "4.2.0"
    gatsby-plugin-typescript "3.2.0"
    gatsby-remark-copy-linked-files "3.2.0"
    gatsby-remark-image-attributes "1.0.0-4"
    gatsby-remark-prismjs "4.2.0"
    gatsby-source-filesystem "3.2.0"
    gatsby-transformer-remark "3.2.0"
    github-slugger "1.3.0"
    globby "11.0.0"
    graphql "^15.5.0"
    gray-matter "^4.0.3"
    history "^5.0.0"
    is-relative-url "^3.0.0"
    is-text-path "^2.0.0"
    is-url "^1.2.4"
    js-yaml "^3.14.1"
    lodash "^4.17.21"
    lodash.throttle "^4.1.1"
    marked "^0.7.0"
    mdast-util-to-string "^2.0.0"
    mobx "~6.1.0"
    node-fetch "^2.6.1"
    p-map "^4.0.0"
    path-browserify "^1.0.1"
    polished "^4.1.2"
    prismjs "^1.23.0"

and

"@redocly/openapi-cli@~0.12.1":
  version "0.12.16"
  resolved "https://registry.yarnpkg.com/@redocly/openapi-cli/-/openapi-cli-0.12.16.tgz#e6be4dba845a506af5c19a428cfa62c53fc46176"
  integrity sha512-TT0fNYITnGanoOTR1MKLrjazhl3lnAimCW260cbMy3zu2wpTKXrwVaNj0gmdvMFHbqfYTSS0BOKVA3hLPdMsNg==
  dependencies:
    chalk "^3.0.0"
    chokidar "^3.3.1"
    commander "^5.0.0"
    handlebars "^4.7.3"
    js-yaml "^3.13.1"
    lodash.isequal "^4.5.0"
    merge-deep "^3.0.2"
    minimatch "^3.0.4"
    node-fetch "^2.6.0"
    portfinder "^1.0.25"
    simple-websocket "^8.1.1"
    yaml-ast-parser "0.0.43"

Also - I have no idea how this got here:

06:36 Sun 08-Aug-21 [/bench/current/plexure/work/redocly/px_api_2]
my_prompt  > npx openapi-cli
$HOME/.npm/_npx/5309e354758d5c1c/node_modules/.bin/openapi-cli: 1: $HOME/.npm/_npx/5309e354758d5c1c/node_modules/.bin/openapi-cli: use strict: not found
$HOME/.npm/_npx/5309e354758d5c1c/node_modules/.bin/openapi-cli: 3: $HOME/.npm/_npx/5309e354758d5c1c/node_modules/.bin/openapi-cli: Syntax error: "(" unexpected

and

06:39 Sun 08-Aug-21 [/bench/current/plexure/work/redocly/px_api_2]
my_prompt > cat $HOME/.npm/_npx/5309e354758d5c1c/node_modules/.bin/openapi-cli

---
'use strict';

exports.validate = function() {
    console.log("This is my first npm");
};
---

and

06:42 Sun 08-Aug-21 [/bench/current/plexure/work/redocly/px_api_2]
my_prompt >  yarn outdated
yarn outdated v1.22.11
Done in 9.62s.

Redocly / developer-portal-starter