Document private web API

Question

We set up a web API for project internal usage. I'm looking for a nice way to document our API. I've searched the web and found

• IO Docs
• Swagger

These tools read in JSON files that can be created automatically, e.g. for Java. Our API has grown and I like to create the JSON manually, but not by hand in a text editor. Is there a tool or frontend that eases the burden of creating the descriptive JSON manually?

On the other hand, what are recommendable tools for the documentation of a web API?

Answer 1

I work in a .NET (C#) shop and we use swagger to document our apis. We couldn't find any tools to do what your asking...so we just created our own. I don't think swagger is mature enough to spawn utility projects like that...yet.

It was not to difficult to create classes to represent the json objects described by the swagger documentation. We just take these instantiated classes and run them through a JSON serializer to get our individual json files describing our endpoints.

Best of luck!