Hey everyone! I'm trying to decide how to best document my APIs with OpenAPI. Ideally, I want to streamline the process to avoid too much manual work since keeping everything up-to-date can get cumbersome. I've seen several methods, including using decorators, comments, magic code for validation rules, model parsers, and various file formats that can convert to openapi.json. Personally, I've been utilizing integration tests to auto-generate around 80% of my OpenAPI spec by capturing requests and responses, then I just merge in the rest from a pre-written JSON file. There are also tools like Swagger and ReDoc for rendering, but I'm particularly interested in hearing about your preferred automation techniques for this task and why you think they work best!
3 Answers
I mostly use decorators in my Express app to generate OpenAPI docs. I have mixed feelings about it, but it does the job. Ideally, I want a solution like itdoc.kr; it looks promising, but it seems to be lacking some features right now. My goal is to not write things manually, since I want my API to be the source of truth. If my types can be inferred without extra overhead, that's a win for me! The less I have to think about it, the better.
You didn't mention which language or framework you’re using, but most modern frameworks come with OpenAPI generator support. If you’re flexible, some frameworks have built-in API documentation capabilities that make life a lot easier!
I usually go for TypeScript or PHP for backend work. If you have any recommendations for frameworks or packages that work well with OpenAPI in those languages, I'd love to hear them!
I find decorators to be the cleanest method for docs, even if they add a bit of noise to the code. I actually use a workflow where I call a series of functions to scan endpoints, generate schemas, validate the OpenAPI spec, review it, and finally publish the docs. This approach keeps everything organized, and I can checkpoint each step for review. Plus, it works with different methods—be it decorators, comments, or separate files!
Totally get that! Manual documentation can be such a hassle, and I feel like AI-generated docs just won't cut it because they keep evolving. It’s better to integrate documentation into the coding process itself to avoid extra maintenance.