Generate API documentation

[baohouse]

Description

It would be useful to have API documentation using a generator.

This will also be useful for #883.

---

Please assign yourself (via the Assignees dropdown), if you do want to work on this issue. Can't find yourself? You need to join our organization.

Check out our Picking Up Issues guide if you haven't already!

[denys-medynskyi]

Hi @baohouse I can do it, however, I don't see any API folder. Can you point me which one should be documented? Or which files exactly should be documented?

Also, regarding the API documentation. I think the most easy to do and easy to maintain is markdown documentation with code snippets.

What do you think about markdown docs?

[member-cop[bot]]

Hey @denysmedynskyi, thanks for expressing your interest. We would love your help with this issue. Please follow these next steps to join our contributor community.

[julianguyen]

@denysmedynskyi So we don't have API docs at all, so this would be starting from scratch. While working on this, I wouldn't remove the logic that exists in the controller as we need backward compatibility.

[denys-medynskyi]

Do you mean by starting commenting existing endpoints? Can you give me an example what you want in the end?

[member-cop[bot]]

Hey @denysmedynskyi, thanks for expressing your interest. We would love your help with this issue. Please follow these next steps to join our contributor community.

[julianguyen]

@denysmedynskyi Great question. I think we want to extend the existing API have in our controller but write them in a way so that it can easily be used in the client without relying on Rails views and routing. We would want proper JSON responses.

Generating docs would be helpful too, Swagger UI is great for that.

@baohouse was there anything else I missed?

[baohouse]

Yah, Swagger is probably the tool of choice; can't go wrong with that. If we're using Swagger, then the work here is not so much creating JSON input/output, but is more about properly annotating the controller. It would look like this:

https://www.sitepoint.com/do-the-right-thing-and-document-your-rails-api-with-swagger/

class Api::V1::UsersController < ApplicationController
  .....
  # POST /users
  swagger_api :create do
    summary "To create user"
    notes "Implementation notes, such as required params, example queries for apis are written here."
    param :form, "user[name]", :string, :required, "Name of user"
    param :form, "user[age]", :integer, :optional, "Age of user"
    param_list :form, "user[status]", :string, :required, "Status of user, can be active or inactive"
    response :success
    response :unprocessable_entity
    response :500, "Internal Error"
  end
  def create
    @user = User.new(user_params)
    if @user.save
      render json: @user, status: :created
    else
      render json: @user.errors, status: :unprocessable_entity
    end
  end
  .....
end

[member-cop[bot]]

Hey @baohouse, thanks for expressing your interest. We would love your help with this issue. Please follow these next steps to join our contributor community.

[julianguyen]

Omg this bot lol

[alexiamcdonald]

Hello! I started this but I have become stuck on react component issues. Maybe if someone who knows react better than me could have a look that would be great.