[ ] That page documents at least one route for one of the controller routes under app/controllers/api
[ ] That page can be used to interact with the API, but only if the user authenticates in some way (which could by logging in through the normal UI, or some other way
[ ] There is a clear example in the code base of how to add the rest of the controller routes under app/controllers/api to the swagger documentation
Discussion
There are a couple of gems that may be useful here. Without further research, we don't know which one is the most straightforward approach:
rswag ( https://github.com/rswag/rswag ) seems to require rspec as well, but might have the advantage that you run write tests and documentation in the same file using rspec syntax.
swagger-docs ( https://github.com/richhollis/swagger-docs ) is a different gem which may be easier or may be more difficult to work with. Hard to say without trying both.
It may be helpful to start with a new rails project from scratch (say, a simple CRUD on todos from some rails tutorial) and try to add a swagger api to that first as an exercise. That would also give you some good practice with rails.
US
Acceptance Criteria
app/controllers/apiapp/controllers/apito the swagger documentationDiscussion
There are a couple of gems that may be useful here. Without further research, we don't know which one is the most straightforward approach:
rspecas well, but might have the advantage that you run write tests and documentation in the same file usingrspecsyntax.It may be helpful to start with a new rails project from scratch (say, a simple CRUD on todos from some rails tutorial) and try to add a swagger api to that first as an exercise. That would also give you some good practice with rails.
A few web pages that may help
Add more as you find them:
swagger-doc: https://coderwall.com/p/bjk3pa/documenting-rails-based-rest-api-using-swagger-uirswagandrspec: https://medium.com/@sushildamdhere/how-to-document-rest-apis-with-swagger-and-ruby-on-rails-ae4e13177f5d