Hi,
so we have our beautiful set of APIs that adheres to JSON:API specification.
Now, is there a suggested way to create documentation for the APIs?
Well, without using some API description language, unless you think is necessary.
Any tool for create API documentation you want to share is appreciated!
I don’t know of any tools (though others might!), but one of the nice things about JSON:API-compliant APIs is that they all work the same way for tasks like sorting, filtering, etc etc. So, all an individual API really has to document is its different models, urls, and perhaps things like which optional parts of the spec it supports.
Therefore, what I’ve done in my personal projects is just document the models etc (in a human readable table) and then point users to the JSON API specification and examples page (or to this forum) for details on using all the other features.
That’s not a perfect solution, since the spec can still be a bit hard for newcomers to penetrate (help with that would be very much appreciated!), but it works ok, and will only become a better option as more people get familiar with JSON API.
Hope that helps at least a bit!
P.S. Here’s the template I use for documenting all my models. It’s reasonably pretty and I could spin it out into a standalone project (with better documentation about the input data format) if there’s demand.
I am definitely curious to how people are documenting their APIs too. FWIW, at my work we are documenting our JSON API with raml.
To Ethan’s point about query parameters (sorting, filtering, etc.). I’ve found that RAML’s traits are nice because we can essentially DRY up those query parameters leaving only what is unique to a model (e.g. a requesting a client requesting an article resource can also include tags) to be determined when documenting an endpoint.
Another compelling reason why we opted for RAML were its sample projects such as this: http://docs.raml.org/apis/instagram/
I’m very happy with API Blueprint for documenting REST APIs, so it is well suited for JSON API. There is a hosted service for it: APIARY. And a lot of great tooling, a lot around automated testing. I’m not affiliated with them, just a fan 
Here is an example how we used it for a generic account JSON API:
http://docs.accountjsonapi.apiary.io
I’m very curious what other people are using though. Maybe we could at a list of “Projects using JSON API” on the website? We are still very new to JSON API, and I’m sure we have tons of issues in our spec, and learning from others is always a great way to get better at it.