Overview documentation for the Solidus API #2714
Conversation
|
@jhawthorn I have spent some time looking into ways that we can generate REST API documentation from the existing specs, but I haven't come across anything that wouldn't require additional dependencies and DSL-beyond-RSpecland. If you have any recommendations/preferences, I'd be interested to hear about them. I'm happy to do any of the work that comes along with making this happen. |
benjaminwil
force-pushed
the
api_docs/initial
branch
from
0468651
to
1da6fbe
Compare
|
Hello, I am currently managing an API service in the project in which I am working. I'd like to share our experience. In our case, unlike @benjaminwil , we wanted to automate the generation of the documentation starting right from the tests. We have greatly appreciated how this approach is amalgamated within an agile environment. Initially we tried to use Dredd. It has a very Rspec-based DSL very intuitive and descriptive, but needs Node for the generation and maintenance of the SwaggerUI. In the end we used Rswag, also based on Rspec-land, but trying to improve its DSL. It is based on Swagger2.0 and it is limited but it suites our first API version. We are now thinking again to Dredd, beacuse other gems have necessitated the installation of Node as a dependency. |
guides/api/overview.md
Outdated
| - Successful `GET` requests always return a status of `200`. | ||
| - Successful `CREATE` and `UPDATE` requests result a status of `201` and | ||
| `200`. | ||
| - Successful `DELETE` requests return a status of `200` and no content. |
There was a problem hiding this comment.
If I'm not wrong, successful DELETE return a status of 204
Ideally, this document will provide a one-page view of the Solidus API endpoints. At the moment, I am not able to generate a helpful, clean document with the available endpoints. For now, this file helps API users find the existing endpoints.
benjaminwil
force-pushed
the
api_docs/initial
branch
from
1da6fbe
to
9d61197
Compare
These brief articles provide basic information for anyone who wants to use the Solidus API for the first time.
What to expect in future API docs PRs
In the future, I would like to extend and improve the
endpoints.mdarticle to list useful information about all of the API endpoints. This might include information about specific or special parameters, common API calls, or particularly unusual requests.But I would prefer to generate this documentation from existing (or new) tests as much as possible. Updating and maintaining API docs needs to be done explicitly alongside the code.