Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Add a `GET /api/v1/openapi.json` endpoint and remove the need for a build-time export to read the spec

Open
  • Is something wrong?
#224 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
38/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
github-actions, nodejs, openapi, typescript
Domain
backend-api-design, ci-cd

Research direction

Start with scripts/export-openapi.ts to see how the app is booted to build the spec, then with the document builder setup in src/main.ts. The CI stubs are at .github/workflows/build-check.yml lines 47-53. Done means /docs/openapi.json returns the same spec that npm run openapi:export writes, Swagger UI is off in production by default, and CI runs without fake DATABASE_URL and JWT_SECRET values.

Written by the indexing model from the issue text.

Description

documentation enhancement help wanted intermediate

Problem

The OpenAPI spec is only obtainable by running a build-time export script:

npm run openapi:export   # scripts/export-openapi.ts, requires NODE_ENV and a bootable app
npm run openapi:validate # scripts/validate-openapi.ts

scripts/export-openapi.ts has to boot the Nest application, which is why CI has to supply DATABASE_URL, JWT_SECRET and PORT just to produce a spec (.github/workflows/build-check.yml:47-53), with the comment that the script "boots with abortOnError:false so it tolerates DB absence". Meanwhile there is no runtime route that serves the spec.

@nestjs/swagger v7 is already a dependency and the document builder is presumably configured in src/main.ts, which means the spec exists in memory at runtime — it is simply not exposed.

Why it matters

Anyone wanting to generate a client, inspect the API, or write an integration must clone the repo, install dependencies, and run a script that pretends to be a server. That is a significant barrier for an SDK-publishing project whose README advertises the spec at /docs/openapi.json — a path that does not currently exist at runtime.

The CI workaround is also a smell: the spec generation needs a fake database URL, which means a malformed environment produces a silently incomplete spec rather than a clear failure.

Suggested Direction

  1. Expose the document builder's output. @nestjs/swagger generates the spec once the app has started. Either serve the pre-built docs/openapi.json as a static asset, or build the document without booting the full application (create an application context rather than a full app, if the version supports it — this avoids the database problem entirely).
  2. Serve it at a stable URL, matching what the README already claims — /docs/openapi.json — and serve Swagger UI alongside it. swagger-ui-express and serve-favicon are already dependencies, so check whether UI setup exists.
  3. Restrict in production. An unauthenticated, always-current spec is an information leak about internal routes. Gate it behind an env flag or restrict to non-production, consistent with how the README treats other internal endpoints.
  4. Simplify CI once the spec no longer needs a booted app — remove the DATABASE_URL/JWT_SECRET stubs from .github/workflows/build-check.yml and let openapi:export run cleanly.

Constraints

  • The generated spec must stay byte-comparable with what the SDK pipeline consumes, or the published SDKs change shape.
  • The spec is generated from controller decorators, so it inherits the existing gaps — 377 routes carry only 209 @ApiResponse decorators. Do not fix that here; see the OpenAPI-documentation issue.
  • Swagger UI must not be exposed publicly by default.

Acceptance Criteria

  • The OpenAPI spec is reachable at a documented URL without running an export script.
  • npm run openapi:export still produces a spec identical to the served one.
  • Swagger UI is available and gated appropriately for production.
  • CI no longer needs fake database credentials to generate the spec.
  • The README's /docs/openapi.json claim is now accurate.
Dominant language
TypeScript
Stars
7
Forks
55
Avg merge
1d 17h
Merged PRs (30d)
5

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from SourceXXL/alian_structure-api

All issues in SourceXXL/alian_structure-api

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.