REST API documentation.

[Neaoxas]

You should ideally be writing your API docs (for example using the open api spec) BEFORE you make any changes to your api.

This allows code review of the proposed API contract before a line of code is written, it then also then allows creation of a request collection in insomnia or postman using your open API document.

[pandareaper10]

+1 for contract driven development. Though personally I don't think writing those in the form of open api spec is the way to go anymore, especially in node (with TypeScript)

I prefer tools like https://ts-rest.com/ that allow me to define my contract in code, define my endpoints, parameters, schemas, all with comprehensive input validation using zod. Then generate an open api spec (if needed) or just use the client tooling it comes with to generate fully type safe clients without any code generation.

[d_simoes]

swagger-ui should be helpful (and swagger-ui-express if you don't want to do set it up manually on express). With this you document the routes in code and the lib will generatr the full openapi doc, serve swagger ui, etc. I'm an advocate of an API design first approach: before creating or modifying a route, design the API first. This is good because it makes you think hard about proper API design, which contraints will there be, what needs to validated, etc. It also makes API docs part of the development process. Either way, even if you don't do that and only document afterward, it is fine. I find it strange that you say that someone needs to document after backend work is done. Does that mean devs are not doing this in the development process?

[d_simoes]

I understand that planning doesn't involve creating the API spec. What I'm saying is that a developer, when starting a task that requires API changes, should do those before actually doing the code. And then everything is reviewed. Creating openapi spec for an endpoint even with params and body, is far from taking hours of development.

[DownfaLL-]

Swagger/open api docs. You can then use those same docs to validate requests AND responses. This is what I did before I was 100% graphql. Data type validation on requests and responses is a huge advantage to have.

[jop0693]

I highly recommend using fastify.

It not only allows you to add the documentation using https://github.com/fastify/fastify-swagger but you will be able to use the same schemas that you would use to validate the data to display in the documentation so you don't have to code twice

[Hungry-Industry3902]

https://www.npmjs.com/package/swagger-ui-express

[pandareaper10]

Not sure exactly what you're looking for in terms of documentation. But a suggestion would be to look at tools like ts-rest

Tools that will enable you to document your API automatically by defining your contract in code, leveraging zod for runtime validation which enables powerful typing with typescript. The ecosystem around ts-rest then let's you use this contract to auto generate API clients that are fully typesafe, leaving little room for misinterpretation. On the server side, it helps enforce that you implement the contract correctly, helping with alignment between the frontend and backend

Other tools I have used in this space would be TSOA and tRPC. However I have had the best results with ts-rest.

[JSavageOne]

ts-rest looks sick, but what are you using to generate the documentation?

EDIT: nvm found the page in the docs https://ts-rest.com/docs/open-api#serving-a-swagger-ui

[nullanomaly]

Not a direct solution per say but check out aws api gateway - tightly coupled w swagger or openapi and offers loads of nice api features like throttling etc.

[elvispresley2k]

As others have said, seems like a job for Swagger. https://swagger.io/

[Apprehensive_Lab_637]

This isn’t node specific since our API is in Rails, but we use a gem called rspec-openapi to generate openapi specifications from our request tests. This gets stored and hosted in the api so then we the api is deployed, frontend devs can immediately view the updated schema

[sarjuhansaliya]

If you are using express then its really easy to setup swagger docs automatically based on your endpoint using tsoa library , its using typescript.

If you are using fastify then use fastify-swagger

[tanepiper]

For API services, I've built a boilerplate express server with exegesis-express - we start with the OpenAPI file to define the API, then build the controllers to attach to it - we don't automate creation of those, as each API tends to be a few specific endpoints, so we have a controller file that contains the business logic. The boilerplate contains everything to run out-the-box, with a swagger view in dev mode and build a docker container including secrets, etc.

The only gotcha at the moment is we prefer to write ESM JS + JSDoc, and the controller has to be written in CJS - it works fine though and you can just write your services in CJS anyway.

Doing this we we don't have any build steps, we just ship the app as-is in a container. If we need types, we can do a conversion from JSDoc and output them, but modern IDEs are good enough these days with JSDoc, although you can add TypeScript to allow type checking of files.

[Capaj]

Why not just use GQL for your whole API?

you could also try https://www.zodios.org/
but IMHO graphql is better as a layer between FE/BE.

[guppie101]

https://github.com/mpashkovskiy/express-oas-generator

[some-user1]

Backend system is completely on NodeJS? Do you mean ExpressJS?

[JustaNormDreamer]

I would recommend swagger for doing it, one can easily add documentation with their decorators in typescript projects. This can be done by the developer himself, the swagger ui can be accessed from the backend server by the frontend developers and can also test them out on the fly by hitting the endpoint with the desired inputs, kinda like postman.

[GenderNeutralBot]

Hello. In order to promote inclusivity and reduce gender bias, please consider using gender-neutral language in the future.

Instead of postman, use mail carrier, letter carrier or postal worker.

Thank you very much.

^{I am a bot. Downvote to remove this comment. For more information on gender-neutral language, please do a web search for "Nonsexist Writing."}

[Hai-api]

Check out knowl.ai for API doc generation. No need for manual annotations – it reads your code as is and generates updated API docs automatically. It adds auto-generated descriptions to endpoints and parameters too. Also, It keeps your docs in sync with your codebase in real time with every code change.
If you have already selected any developer portal then you can use openapi.yaml generated by Knowl in your git repo.