feat(openapi): adding a command to resolve circular and recursive references #1063

olehshh · 2024-11-11T21:45:54Z

🚥 Resolves RM-10283

🧰 Changes

Adding a script to automate the workaround for circular and recursive references.
Adding this command to the list of existing ones.

🧬 QA & Testing

Take any file with circular references, for example

openapi: 3.0.0
info:
  title: Cyclic Reference Example
  version: 1.0.0
paths:
  /example:
    get:
      summary: Example endpoint with cyclic references
      responses:
        '200':
          description: Successful response
components:
  Schemas:
    ObjectC:
      type: object
      properties:
        test:
          type: string
    ObjectA:
      type: object
      properties:
        test:
          type: string
        relatedObject:
          $ref: '#/components/schemas/ObjectB'
    ObjectB:
      type: object
      properties:
        test:
          type: string
        relatedObject:
          type: array
          items:
            $ref: '#/components/schemas/ObjectA'
        test2:
          $ref: '#/components/schemas/ObjectC'

Execute the rdme openapi:refs [path] command and use inspect to check for circular references after execution. The command also handles recursiveness.

kanadgupta

looks great so far! haven't had a chance to properly test this yet, but some preliminary feedback below! also if you could add some docs in README.md that'd be great. thanks!

kanadgupta · 2024-11-12T14:02:39Z

src/cmds/openapi/refs.ts

+      return 'File path is required.';
+    }
+
+    const openApiData = OpenAPISolvingCircularityAndRecursiveness.readOpenApiFile(spec);


rather than using this static method to read the file, can you use our existing prepareOas function? see an example here:

rdme/src/cmds/openapi/convert.ts

Line 57 in 5db25a1

const { preparedSpec, specPath, specType } = await prepareOas(spec, 'openapi:convert', { convertToLatest: true });

kanadgupta · 2024-11-12T14:04:42Z

src/cmds/openapi/refs.ts

+      }
+    }
+
+    OpenAPISolvingCircularityAndRecursiveness.writeOpenApiFile(spec, openApiData);


rather than overwriting the existing file, can you add a prompt (and a corresponding --out flag) so users can specify what the updated file path should be? see here for an example:

rdme/src/cmds/openapi/convert.ts

Lines 66 to 85 in 5db25a1

prompts.override({

outputPath: opts.out,

});

const promptResults = await promptTerminal([

{

type: 'text',

name: 'outputPath',

message: 'Enter the path to save your converted/bundled API definition to:',

initial: () => {

const extension = path.extname(specPath);

return `${path.basename(specPath).split(extension)[0]}.openapi${extension}`;

},

validate: value => validateFilePath(value),

},

]);

Command.debug(`saving converted/bundled spec to ${promptResults.outputPath}`);

fs.writeFileSync(promptResults.outputPath, JSON.stringify(parsedPreparedSpec, null, 2));

…rity-and-recursiveness

kanadgupta

DM'd you about this but this has a few merge conflicts now with the changes that were shipped in #1068 — happy to help with these if you need a hand!

…napi-adding-command-to-solve-circularity-and-recursiveness

…cursiveness' of https://github.com/readmeio/rdme into oleh/openapi-adding-command-to-solve-circularity-and-recursiveness

…rity-and-recursiveness

…cursiveness' of https://github.com/readmeio/rdme into oleh/openapi-adding-command-to-solve-circularity-and-recursiveness

…rity-and-recursiveness

kanadgupta

more feedback! i'll try and open a PR this week based off of yours with copy edits

kanadgupta · 2024-12-02T20:53:12Z

__tests__/commands/openapi/refs.test.ts

+import { runCommandAndReturnResult } from '../../helpers/oclif.js';
+
+describe('openapi:solving-circularity-recursiveness', () => {
+  let run: (args?: string[]) => Promise<unknown>;


Suggested change

let run: (args?: string[]) => Promise<unknown>;

let run: (args?: string[]) => Promise<string>;

kanadgupta · 2024-12-02T20:56:29Z

src/commands/openapi/refs.ts

+    },
+    {
+      description: 'If you wish to automate this command, you can pass in CLI arguments to bypass the prompts:',
+      command: '<%= config.bin %> <%= command.id %> petstore.json -out petstore.openapi.json',


Suggested change

command: '<%= config.bin %> <%= command.id %> petstore.json -out petstore.openapi.json',

command: '<%= config.bin %> <%= command.id %> petstore.json --out petstore.openapi.json',

kanadgupta · 2024-12-02T21:03:00Z

__tests__/lib/__snapshots__/analyzeOas.test.ts.snap

can you revert this change?

I returned this file, there was some confusion with them(

kanadgupta · 2024-12-02T21:10:52Z

src/commands/openapi/refs.ts

+   * @param {OASDocument} document - The OpenAPI document to analyze.
+   * @returns {Promise<string[]>} A list of circular reference paths.
+   */
+  static async getCircularRefsFromOas(document: OASDocument): Promise<string[]> {


can you go through and remove all of the type definitions that you have in JSDocs (e.g., @param {OASDocument}) and move your parameter docs above the parameters themselves? they're superfluous since you're already are defining the types in your TS function parameter type annotations. see below for an example!

Suggested change

* @param {OASDocument} document - The OpenAPI document to analyze.

* @returns {Promise<string[]>} A list of circular reference paths.

*/

static async getCircularRefsFromOas(document: OASDocument): Promise<string[]> {

* @returns A list of circular reference paths.

*/

static async getCircularRefsFromOas(

/** The OpenAPI document to analyze. */

document: OASDocument,

): Promise<string[]> {

kanadgupta · 2024-12-02T21:12:00Z

src/commands/openapi/refs.ts

+
+    if (remainingCircularRefs.length > 0) {
+      // eslint-disable-next-line no-console
+      console.info(


can you use the info logger from lib/logger instead?

rdme/src/lib/logger.ts

Line 42 in a55dd14

function info(

@olehshh

## 🧰 Changes Touched up a few things in #1063! - [x] Documentation copy edits - [x] Logging touch ups - [x] Makes sure we're only allowing this to be run against OpenAPI - [ ] Adds a stricter type in 81607ca that ends up breaking the build — I believe this is a code smell. @olehshh can you look into fixing the type errors here? ## 🧬 QA & Testing Are my changes sound?

…d-to-solve-circularity-and-recursiveness

This reverts commit 9249d2a.

…rity-and-recursiveness

…cursiveness' of https://github.com/readmeio/rdme into oleh/openapi-adding-command-to-solve-circularity-and-recursiveness

…rity-and-recursiveness

admin added 2 commits November 11, 2024 22:30

Adding refs to the list of openapi commands

59bb8f2

Code to execute the openapi:refs command

d82700a

olehshh changed the title ~~Oleh/openapi adding command to solve circularity and recursiveness~~ docs(openapi): adding a command to resolve circular and recursive references Nov 11, 2024

olehshh changed the title ~~docs(openapi): adding a command to resolve circular and recursive references~~ feat(openapi): adding a command to resolve circular and recursive references Nov 11, 2024

admin added 2 commits November 11, 2024 23:03

style: apply Prettier formatting

099a6f1

Add 'openapi:refs' command and update related test snapshots

95208cf

olehshh requested a review from kanadgupta November 11, 2024 22:28

olehshh added enhancement New feature or request command:openapi Issues pertaining to the `openapi`, `validate`, `reduce`, or `swagger` commands labels Nov 12, 2024

kanadgupta requested changes Nov 12, 2024

View reviewed changes

admin added 2 commits November 14, 2024 14:31

docs(openapi) command description

6249347

fix(openapi) use of a premade solution for processing a file

0a5f141

olehshh requested a review from kanadgupta November 14, 2024 13:37

Merge branch 'next' into oleh/openapi-adding-command-to-solve-circula…

03c092c

…rity-and-recursiveness

kanadgupta requested changes Nov 19, 2024

View reviewed changes

admin and others added 6 commits November 19, 2024 09:43

chore: update package-lock.json

3660917

Merge branch 'next' of https://github.com/readmeio/rdme into oleh/ope…

7ca5197

…napi-adding-command-to-solve-circularity-and-recursiveness

refactor: align code with recent updates

597ece5

Merge branch 'oleh/openapi-adding-command-to-solve-circularity-and-re…

0b87569

…cursiveness' of https://github.com/readmeio/rdme into oleh/openapi-adding-command-to-solve-circularity-and-recursiveness

chore: minor correction

3039ea0

Merge branch 'next' into oleh/openapi-adding-command-to-solve-circula…

dca7b9f

…rity-and-recursiveness

olehshh requested a review from kanadgupta November 19, 2024 14:50

olehshh and others added 8 commits November 19, 2024 18:32

Merge branch 'next' into oleh/openapi-adding-command-to-solve-circula…

349b9f8

…rity-and-recursiveness

Merge branch 'next' into oleh/openapi-adding-command-to-solve-circula…

88bd34e

…rity-and-recursiveness

Merge branch 'next' into oleh/openapi-adding-command-to-solve-circula…

0a3c4e0

…rity-and-recursiveness

test: openapi:refs

0c0027e

Merge branch 'oleh/openapi-adding-command-to-solve-circularity-and-re…

18f7b4e

…cursiveness' of https://github.com/readmeio/rdme into oleh/openapi-adding-command-to-solve-circularity-and-recursiveness

Merge branch 'next' into oleh/openapi-adding-command-to-solve-circula…

8fcc065

…rity-and-recursiveness

Merge branch 'next' into oleh/openapi-adding-command-to-solve-circula…

9fa0ca3

…rity-and-recursiveness

Merge branch 'next' into oleh/openapi-adding-command-to-solve-circula…

a4b1fc0

…rity-and-recursiveness

Oleh Shumov added 3 commits December 2, 2024 21:51

chore: deleting a file

91dbb5a

chore: oops

6de2193

Merge branch 'next' into oleh/openapi-adding-command-to-solve-circula…

a55dd14

…rity-and-recursiveness

olehshh requested a review from kanadgupta December 2, 2024 21:06

kanadgupta reviewed Dec 2, 2024

View reviewed changes

refactor: requested changes

ce09500

olehshh requested a review from kanadgupta December 2, 2024 21:38

olehshh self-assigned this Dec 4, 2024

kanadgupta mentioned this pull request Dec 5, 2024

fix: openapi:refs touch ups #1103

Merged

4 tasks

kanadgupta removed this from the v9 milestone Dec 5, 2024

kanadgupta and others added 8 commits December 5, 2024 18:33

test: schemes without properties

9c037c9

Merge remote-tracking branch 'origin' into oleh/openapi-adding-comman…

da5b0ad

…d-to-solve-circularity-and-recursiveness

chore: minor updates

9249d2a

Revert "chore: minor updates"

dd02080

This reverts commit 9249d2a.

chore: minor updates

4355f9c

chore: lint

a7d8555

Merge branch 'next' into oleh/openapi-adding-command-to-solve-circula…

f010a7d

…rity-and-recursiveness

olehshh marked this pull request as draft December 6, 2024 18:40

Oleh Shumov added 4 commits December 7, 2024 23:31

feat: processing schemas with only (beta)

f7e52bf

Merge branch 'oleh/openapi-adding-command-to-solve-circularity-and-re…

8bcf655

…cursiveness' of https://github.com/readmeio/rdme into oleh/openapi-adding-command-to-solve-circularity-and-recursiveness

chore: lint

2667d1b

chore: cleanup

1d119f2

olehshh marked this pull request as ready for review December 8, 2024 15:16

Oleh Shumov and others added 6 commits December 9, 2024 13:01

chore: cleanup

e790dec

test: complex case

ae39d1e

Merge branch 'next' into oleh/openapi-adding-command-to-solve-circula…

6e65d9f

…rity-and-recursiveness

Merge branch 'next' into oleh/openapi-adding-command-to-solve-circula…

91958bd

…rity-and-recursiveness

Merge branch 'next' into oleh/openapi-adding-command-to-solve-circula…

09b8039

…rity-and-recursiveness

Merge branch 'next' into oleh/openapi-adding-command-to-solve-circula…

4011248

…rity-and-recursiveness

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(openapi): adding a command to resolve circular and recursive references #1063

feat(openapi): adding a command to resolve circular and recursive references #1063

olehshh commented Nov 11, 2024 •

edited

Loading

kanadgupta left a comment

kanadgupta Nov 12, 2024

kanadgupta Nov 12, 2024 •

edited

Loading

kanadgupta left a comment

kanadgupta left a comment

kanadgupta Dec 2, 2024

kanadgupta Dec 2, 2024

kanadgupta Dec 2, 2024

olehshh Dec 2, 2024

kanadgupta Dec 2, 2024

kanadgupta Dec 2, 2024

	prompts.override({
	outputPath: opts.out,
	});

	const promptResults = await promptTerminal([
	{
	type: 'text',
	name: 'outputPath',
	message: 'Enter the path to save your converted/bundled API definition to:',
	initial: () => {
	const extension = path.extname(specPath);
	return `${path.basename(specPath).split(extension)[0]}.openapi${extension}`;
	},
	validate: value => validateFilePath(value),
	},
	]);

	Command.debug(`saving converted/bundled spec to ${promptResults.outputPath}`);

	fs.writeFileSync(promptResults.outputPath, JSON.stringify(parsedPreparedSpec, null, 2));

	let run: (args?: string[]) => Promise<unknown>;
	let run: (args?: string[]) => Promise<string>;

	command: '<%= config.bin %> <%= command.id %> petstore.json -out petstore.openapi.json',
	command: '<%= config.bin %> <%= command.id %> petstore.json --out petstore.openapi.json',

feat(openapi): adding a command to resolve circular and recursive references #1063

Are you sure you want to change the base?

feat(openapi): adding a command to resolve circular and recursive references #1063

Conversation

olehshh commented Nov 11, 2024 • edited Loading

🧰 Changes

🧬 QA & Testing

kanadgupta left a comment

Choose a reason for hiding this comment

kanadgupta Nov 12, 2024

Choose a reason for hiding this comment

kanadgupta Nov 12, 2024 • edited Loading

Choose a reason for hiding this comment

kanadgupta left a comment

Choose a reason for hiding this comment

kanadgupta left a comment

Choose a reason for hiding this comment

kanadgupta Dec 2, 2024

Choose a reason for hiding this comment

kanadgupta Dec 2, 2024

Choose a reason for hiding this comment

kanadgupta Dec 2, 2024

Choose a reason for hiding this comment

olehshh Dec 2, 2024

Choose a reason for hiding this comment

kanadgupta Dec 2, 2024

Choose a reason for hiding this comment

kanadgupta Dec 2, 2024

Choose a reason for hiding this comment

olehshh commented Nov 11, 2024 •

edited

Loading

kanadgupta Nov 12, 2024 •

edited

Loading