Auto generate OpenAPI spec JSON, generate MDX files and update mint.json

[SniperBuddy101]

What is this pull request for? This generates an OpenAPI spec JSON file before building the server. The file is then saved in the docs directory.

Steps after this: We have to scrape the JSON file and generate MDX files for the spec JSON.

[SniperBuddy101]

@arielweinberger The build is failing. Will see what the problem is. Any idea why that might be? Have added a depends_on for a script in project.json.

[arielweinberger]

Pretty sure the issue is related to the scope at which the npx ts-node script is running and some TypeScript configuration. Try using npx tsx instead and let me know how it goes. Also worth trying setting the cwd of the operation (in nx:run-commands) to the server folder. Not sure if Root would work in this case.

[SniperBuddy101]

@arielweinberger npx tsx is failing on my local machine with the following error:

nx run server:generate-open-api-spec

[Nest] 40471  - 10/10/2023, 3:30:27 AM     LOG [NestFactory] Starting Nest application...
[Nest] 40471  - 10/10/2023, 3:30:27 AM   ERROR [ExceptionHandler] Cannot read properties of undefined (reading 'get')

This is the project.json command:

"generate-open-api-spec": {
      "command": "npx tsx --tsconfig apps/server/tsconfig.app.json apps/server/scripts/generate-openapi-spec-json.ts"
    },

With ts-node, it works fine on my local machine. Also, was wondering if the Git repo will be updated when we build the server for Mintlify to consume the updated file.

[arielweinberger]

@SniperBuddy101 It won't be updated. In that case, maybe we should just make a script that generates the spec file + builds the docs, and that spec file is then pushed to source control manually? That'll do for now.

[SniperBuddy101]

@arielweinberger Since, you mentioned manual push to source control, do we need an offline script for this?

I read the Mintlify docs and saw that they had their custom GitHub build mechanism. Don't think we are using that.

[arielweinberger]

@SniperBuddy101 We actually do! Whenever you run npx nx graphql:schema-generate server it will bootstrap the server in offline mode (all online dependencies are mocked). You could try using that to generate a local file and save it in the local filesystem.

We could also create a new script, called npx nx openapi:generate server that works in a similar fashion, but separate for good practice/cache-ability. I don't mind.

[SniperBuddy101]

Yes, so, an offline script to generate the openapi spec file and update the mint.json in offline mode. This won't run on Github actions.

I was thinking if we can modify the mintlify build process and generate the spec and update the mint.json file. But their docs do not contain that: https://mintlify.com/docs/quickstart#1-deploying-your-docs-repository

[arielweinberger]

I think that's fine for now. You're right. We don't use GH actions to build and deploy Mintlify. I find Mintlify to be very aesthetically pleasing but very limited in options. Might move away from it later.

[SniperBuddy101]

@arielweinberger Have created a script that will auto-generate OpenAPI JSON, scrape the JSON, generate MDX files and update mint.json. Command: npx nx generate-open-api-spec server

[arielweinberger]

You rock!