Is the tool working?

[raproid]

I'm having trouble understanding how the tool works.

I want to generate an output spec file to try to feed to Readme.
For that, I do the following:

1. git clone https://github.com/alchemyplatform/docs-openapi-specs
2. npm i
3. cp .env.template .env
4. Set up the Readme key in RDME_API_KEY in .env.
5. Try to create an output spec for an Ethereum method https://github.com/alchemyplatform/docs-openapi-specs/blob/main/ethereum/eth_getBalance.yaml — npm run create ethereum/eth_getBalance.yaml

First, it throws an error for the wrongly formatted operationID: error alchemy-operation-operationId-casing operationId must be kebab cased and without digits. components.pathItems.path.post.operationId
I experiment and change the value: operationId: eth-getBalance -> operationId: eth-getbalance

Now it throws an error while trying to get to the schemas.yaml file:

Linting spec
No results with a severity of 'error' found!
Uploading new spec.. 🧨
File path => ethereum/eth_getBalance.yaml
node:internal/process/promises:279
            triggerUncaughtException(err, true /* fromPromise */);
            ^

Error: Error resolving $ref pointer "/Users/username/Projects/components/schemas.yaml#/Id". 
"/Users/username/Projects/components/schemas.yaml" not found.
    at $Refs._resolve (/Users/username/Projects/docs-openapi-specs/node_modules/@openapi-generator-plus/json-schema-ref-parser/lib/refs.js:153:11)
    at dereference$Ref (/Users/username/Projects/docs-openapi-specs/node_modules/@openapi-generator-plus/json-schema-ref-parser/lib/dereference.js:140:23)
    at crawl (/Users/username/Projects/docs-openapi-specs/node_modules/@openapi-generator-plus/json-schema-ref-parser/lib/dereference.js:69:28)
    at crawl (/Users/username/Projects/docs-openapi-specs/node_modules/@openapi-generator-plus/json-schema-ref-parser/lib/dereference.js:78:30)
    at dereference$Ref (/Users/username/Projects/docs-openapi-specs/node_modules/@openapi-generator-plus/json-schema-ref-parser/lib/dereference.js:160:24)
    at crawl (/Users/username/Projects/docs-openapi-specs/node_modules/@openapi-generator-plus/json-schema-ref-parser/lib/dereference.js:69:28)
    at crawl (/Users/username/Projects/docs-openapi-specs/node_modules/@openapi-generator-plus/json-schema-ref-parser/lib/dereference.js:78:30)
    at dereference$Ref (/Users/username/Projects/docs-openapi-specs/node_modules/@openapi-generator-plus/json-schema-ref-parser/lib/dereference.js:160:24) {
  toJSON: [Function: toJSON],
  [Symbol(nodejs.util.inspect.custom)]: [Function: inspect]
}

The components folder is definitely where it's supposed to be ( in the docs-openapi-specs folder) and the schemas.yaml with all its content — in the components folder. I don't understand why the script is trying to find it in /Projects/components and not in /Projects/docs-openapi-specs/components, but even I cp this folder to /Projects/ the scrips still throws the same error.

What am I doing wrong and how to reach the desired outcome — an output yaml file conforming to the OAPI standards, which I can feed to Readme and see what it generates from it?

[taoyouxian]

I also meet this problem.
Now I just move it to the root directory, change the $ref and add x-readme.
Use npm run update eth_accounts.yaml.

[taoyouxian]

Now, I find a new solution.

1. Update create.js as below
2. Run npm run create example.yaml, this will generate the id and upload the file
3. You can login in the Readme and update the link of this file

require('dotenv').config();

const fs = require('node:fs');
const { parse, stringify } = require('yaml');
const parser = require('@openapi-generator-plus/json-schema-ref-parser');
const { Readme } = require('./Readme');

// TODO: lint OpenAPI?
(async () => {
  // see https://www.npmjs.com/package/rdme#authentication
  const key = process.env.RDME_API_KEY;
  if (!key) {
    throw new Error('Please set RDME_API_KEY in .env');
  }
  
  const filePath = process.argv[2];
  if (!filePath || !filePath.endsWith('.yaml')) {
    throw new Error('Please provide a YAML file (.yaml)');
  }
  console.log(`File path => ${filePath}`);

  const contents = fs.readFileSync(filePath, 'utf-8');
  const originalSpec = parse(contents);

  // derefSpec will have replaced refs with imported definitions
  const derefSpec = await parser.dereference(filePath);

  // spec needs to be string to upload to readme
  const spec = JSON.stringify(derefSpec, null, 2);

  // 3. Upload new specification / get id back from Readme API
  const readme = new Readme(key);
  const id = await readme.spec.upload({ spec });

  console.log();
  console.log(`Upload done with id ${id} (x-readme.id)\n`);