I’ve just finished building a fairly large API and now I need to document it for the rest of my team and potential external partners. I want something that stays in sync with the code so I don't have to manually update a PDF every time I change a field. Is Swagger/OpenAPI still the go-to, or are there newer tools that provide a better developer experience?
3 answers
OpenAPI (formerly Swagger) is still the absolute standard, but the way we use it has evolved. Instead of writing YAML files by hand, most developers now use decorators or docstrings directly in their code (like inversify-express-utils or FastAPI in Python) to auto-generate the JSON spec. For the "UI" side, Redoc is currently very popular because it looks much cleaner and more professional than the classic Swagger UI. Another great option is Stoplight, which provides a more collaborative environment if you have a larger team of technical writers and developers working on the same documentation.
Does Postman have a way to automatically sync its collections with an OpenAPI spec file hosted on GitHub?
I highly recommend checking out Docusaurus with the OpenAPI plugin. It lets you host your API docs alongside your regular project guides in a single, beautiful site.
Docusaurus is great! I love how it handles versioning for documentation, making it easy for users to switch between docs for v1 and v2 of the API.
Yes, Larry, it does! Postman has a feature called "API Builder" that allows you to import an OpenAPI definition directly from a Git repository. Every time you push an update to your spec file, Postman can sync the collection and even update your mock servers. This is incredibly useful for "API-First" development where the documentation and the tests are created before the actual code is written. It ensures that your frontend team is always working against the most up-to-date version of the "contract" between the client and the server.