Hey everyone! I'm curious about the best practices for documenting backend APIs. I personally keep all my API documentation in an OpenAPI JSON file that clearly outlines every endpoint, and I sometimes rely on Postman Collections as well. I'm currently working on software that requires a robust method for importing APIs, so I'm interested in what strategies other developers use for this. How do you document your APIs?
2 Answers
There's a huge ecosystem around OpenAPI. We actually have our backend generate the specification from the code and expose it via a route that requires an API key for access. Client apps can then generate SDKs from this, which helps with type safety and provides React hooks. It’s mostly self-documenting, which saves time later!
I store documentation in Markdown directly in the repo. I have a table of endpoints and worked examples that include responses. Additionally, we keep OpenAPI specs on a '/openapi' endpoint, so the API can self-document. I'm even building an API explorer website that will load APIs dynamically from their OpenAPI specs. It allows team members to interactively test functions, which is pretty cool!
Sounds awesome! I also mainly use OpenAPI specs for documentation, so I'm interested in what other systems are working well right now!