Idea: Add root-level `scripts` and `openapi` folders to the monorepo

[lightwalker-eth]

Background

• An openapi.json file for ENSApi is now being committed directly into our git repo under docs/docs.ensnode.io/ensapi-openapi.json.
  • I don't like how this file lives under the docs.ensnode.io directory in the monorepo. That seems awkward and like an unexpected surprise.
  • It seems it would be better if this file could be accessed via a versioned package for all our OpenAPI specs we publish to NPM?
• Related issue Set foundation for multiple OpenAPI.json files #1600 which notes how we'll be adding multiple openapi.json files and scripts for generating those to the ENSNode monorepo in the future. For example, we should soon work to build openapi.json files for ENSRainbow and ENSIndexer as well. Once available, these openapi.json files should also be added to the ENSNode docs site in a similar way we're currently adding the openapi.json file to the ENSNode docs site for ENSApi. You can also note how in feat(apps/ensadmin): add interactive REST API playground to ENSAdmin #1951 an interactive REST API playground is being added for ENSApi inside of the ENSAdmin UI. We should not add a REST API playground like this to the ENSAdmin UI for ENSIndexer or ENSRainbow. That UI in ENSAdmin is only for ENSApi.
• Looking into the future (outside the scope of this issue) I'm interested to explore building further on our openapi.json files. For example, I'm interested to explore tooling that auto-generates SDKs in many programming languages from an openapi.json file, etc.

Goals

• Organize each of the openapi.json files in a more neutral place within the monorepo.
  • Idea: I'm interested to create a new openapi directory in the root of the monorepo. Inside of this directory, we could create and configure a package.json file for a package named @ensnode/openapi. This package could be versioned in sync with all our other packages and configured for being publicly published to NPM each time we make a release.
  • Inside of this package we could export a .json file for ensapi-openapi.json and in the future also export the openapi.json files for ENSIndexer and ENSRainbow.
  • It would be cool if someone could then import and reference the desired openapi.json files from this package. For example, please review the changes being made in remove mintlify and update docs rest api docs #1940. Here you'll see a number of references across our monorepo being made to docs/ensnode.io/ensapi-openapi.json as references to a relative path. But wouldn't it be nicer we just imported the related openapi.json file such as by writing something like (NOTE: the following is just rough pseudocode and probably won't work) import ensapi.openapi from @ensnode/openapi.

Key open questions

• Please also review our current strategies for how the committed openapi.json files are generated. Where do these script files currently live and should we make any refinements to this? Should the script to generate these live inside the related app? Or should we create a root-level scripts directory in the root of the monorepo for such scripts?
  • NOTE: I'm specifically worried about a script living in app directory X writing openapi.json files to a different app / package directory Y. This feels awkward to me. Is there some more elegant way we could solve for this within our monorepo? Is there some elegant strategy such as symlinks or something clever?

Advice appreciated.

[notrab]

@lightwalker-eth I tried in #1700 use a symlink for the generated spec, and place the generated spec inside /openapi in the root of the repo but Mintlify can't locate these.

Unfortunately that means until Mintlify supports better deploy triggers (controlling what branch or sha to build), we'll have to keep the generated file inside of the docs.ensnode.io context.

[notrab]

@lightwalker-eth I'm not sure what to do with this issue at th emoment. The core issue is that the generated spec file must be remote url, or inside the mintlify docs site as it cannot source something not in the docs.ensnode.io folder.

I think it's fair at this stage that any generated spec can live inside the docs.ensnode.io folder since that's what consumes them to display, and our production URLs will provide those specs anyways for anyone wanting to consume remotely.

[lightwalker-eth]

@notrab Thanks for your actions under this issue! You've made a lot of good progress 🫡

Now that we've changed our plans with Mintlify and won't be using it anymore, maybe it will open up a possibility of achieving the ideas in this issue.

@sevenzing I've just made a significant update to the description in the issue above to refresh it based on work we've advanced over the past few months. I'll transfer assignment of this issue to you for next steps.