A place for developers to talk about building on Farcaster.

/dev

Best tools for generating REST API documentation?

NOTHING beats hand crafting your OpenAPI spec

Often devs go about this the wrong direction: looking for tools that generate OpenAPI/Swagger spec and docs from some code

Instead, start with hand crafting your OpenAPI spec and then use it to generate a client/sdk (ts/go/py/any language) and docs

stainlessapi.com

I found HTTPAPi from  https://github.com/Effect-TS/effect/tree/main/packages/platform to be incredible here. It also gives you a client just from declaring the API

sample: https://github.com/SamuelLHuber/airstack-moxie-api-effect-http

https://github.com/o-az
—
https://x.com/awkroot

I found HTTPAPi from  https://github.com/Effect-TS/effect/tree/main/packages/platform to be incredible here. It also gives you a client just from declaring the API

sample: https://github.com/SamuelLHuber/airstack-moxie-api-effect-http



because generating spec from code ends up being incomplete and tools ignore a bunch of openapi fields. If you read carefully a good openapi spec you’ll understand

Why's it the wrong direction to use tools tho? Just curious

I generally like to have a starting point with a postman collection and then fill in the rest by hand, and that part really is my favorite. Very satisfying

Full Stack Dev | Head of Developer Relations at /pinata | Technical Writer | Tinkering with everything | stevedylan.dev/links

postman is bloated software. I like hopposcotch