Skip to content

Latest commit

 

History

History
355 lines (287 loc) · 9.39 KB

README.md

File metadata and controls

355 lines (287 loc) · 9.39 KB
Raw

API documentation

This is the example of how to generate the API documentation in your rails app.

This application uses the next gems:

APIPIE

Apipie-rails is a DSL and Rails engine for documenting your RESTful API. Instead of traditional use of #comments, Apipie lets you describe the code, through the code.

Getting started

Add the gem to your Gemfile

# Gemfile
gem 'apipie-rails'

Install gem with bundle install && rails g apipie:install

Usage

Describe allowed params and returned properties in the controller:

# app/controllers/api/v1/books_controller.rb

module Api  
  module V1  
    class BooksController < ApplicationController

      def_param_group :book do
        param :id, :number, desc: 'Books id'	  
        param :book, Hash do
          param :title, String, required: true, desc: 'Books title', only_in: :requiest
          param :description, String, desc: 'Books description', only_in: :requiest 
        end

        property :title, String, desc: 'Books title'  
        property :descriprion, String, desc: 'Books description'  
        property :created_at, String, desc: 'Date of the book creation'  
        property :updated_at, String, desc: 'Last time the book was updated'
      end
      
    end	
  end
end

The next step is to describe the HTTP request for your controller actions. Here you can describe the HTTP methods, returned values, response codes, and required params:

# app/controllers/api/v1/books_controller.rb
...
api :GET, '/books/', 'Shows all books'  
returns array_of: :book, code: 200, desc: 'All books'  

def index  
  books = Book.all  
  render json: books  
end

api :POST, '/books/', 'Create a new book'  
returns :book, code: 200, desc: 'Created book'  
param_group :book  

def create  
  book = Book.new(book_params)
  if book.save  
    render json: book, status: :ok  
  else  
    render json: book.errors, status: :unprocessable_entity  
  end  
end

That's all! Follow the link localhost:3000/apipie to check the generated API documentation.

For more information please check out apipie gem documentation

DOX

Dox generates API documentation from RSpec controller/request specs in a Rails application. It formats the output of the tests in the API Blueprint format.

Getting started

Add this line into your Gemfile:

group :test do
  gem 'dox', require: false
end

Run bundle install

Require Dox in the rails_helper and configure RSpec:

# spec/rails_helper.rb

require 'dox'

RSpec.configure do |config|
  config.after(:each, :dox) do |example|
    example.metadata[:request] = request
    example.metadata[:response] = response
  end
end

Then configure the Dox:

# spec/rails_helper.rb

Dox.configure do |config|
  config.header_file_path = Rails.root.join('spec/docs/v1/descriptions/header.md')
  config.desc_folder_path = Rails.root.join('spec/docs/v1/descriptions')
  config.headers_whitelist = ['Accept', 'X-Auth-Token']
end

Create header.md by running the command:

mkdir -p ~/spec/docs/v1/descriptions/ && echo "# [Your app name]" >> header.md

Load descriptions in the rails_helper.rb:

# spec/rails_helper.rb

Dir[Rails.root.join('spec/docs/**/*.rb')].each { |f| require f }

Usage

Define a descriptor module for a resource using Dox DSL:

# spec/docs/v1/books.rb
  
module Docs    
  module V1  
    module Books
      extend Dox::DSL::Syntax
      
      document :api do  
        resource 'Books' do  
          endpoint '/books'  
          group 'Books'  
        end  
      end

      document :index do  
        action 'Index'  
      end
    
      document :create do  
        action 'Create'  
      end

    end  
  end  
end

Include the descriptor modules into your specs:

# spec/request/api/v1/books_spec.rb

require 'rails_helper'  
  
RSpec.describe 'Book', type: :request do  
  include Docs::V1::Books::Api

  let!(:books) { create_list(:book, 10) }

  describe 'GET /books/' do  
    include Docs::V1::Books::Index
    it 'returns all books', :dox do
      get '/api/v1/books'
      expect(response).to be_successful
      expect(json.count).to eq(books.count)
    end
  end

  describe 'POST /books/' do  
    include Docs::V1::Books::Create  
    it 'creates a book', :dox do  
      post '/api/v1/books', params: valid_params  
      expect(response).to be_successful  
      expect(json).to have_key('id')  
      expect(books.count).to be < Book.count  
    end  
  end
end

To generate documentation run:

-f Dox::Formatter --order defined --tag dox --out public/api/docs/v1/apispec.md

The generated documentation path is public/api/docs/v1/apispec.md With this command, you can create a rake task for more comfortable usage:

# lib/tasks/api.rake

namespace :api do
  namespace :doc do
    desc 'Generate API documentation markdown'
    task :generate do
      require 'rspec/core/rake_task'

      RSpec::Core::RakeTask.new(:api_spec) do |t|
        t.pattern = 'spec/request/api/v1/'
        t.rspec_opts = "-f Dox::Formatter --order defined --tag dox --out public/api/docs/v1/apispec.md"
      end

      Rake::Task['api_spec'].invoke
    end
  end
end

Now the documentation can be generated by rake api:doc:generate command.

Renderers

You can render the HTML by yourself with one of the renderers:

Both of them support multiple themes and template customization. Or you can just take your generated markdown and host your documentation on Apiary.io

Apiary

To use apiary, you need to install apiary gem

# Gemfile

gem 'apiaryio', '~> 0.12.0'

Sign up for apiary.io and get your token on API key on this page

Put your API key to the .env:

APIARY_API_KEY=<your_token>

Create a new API project:

Create a new task to publish your API documentation:

# lib/tasks/api.rake

namespace :api do
  namespace :doc do
    ...
    desc 'Publish API documentation to the apiary'
    task :publish do
      `apiary publish --path=public/api/docs/v1/apispec.md --api-name=apiary_api_project_name`
    end
  
  end
end

Now you have well-formatted documentation generated out of the specs to share with your team:

You can find more info about Dox and Apiary here:

RSpec API documentation

Gem rspec_api_documentation generates API documentation from RSpec like the dox gem.

Getting started

Add rspec_api_documentation to your Gemfile

gem 'rspec_api_documentation'

Bundle it:

bundle install

Usage

Set up specs:

mkdir spec/acceptance && touch spec/acceptance/books_spec.rb

Fill your spec file with a code:

# spec/acceptance/books_spec.rb
require 'rails_helper'  
require 'rspec_api_documentation/dsl'  
  
resource 'Books' do  
  let!(:books) { create_list(:book, 10) }  
  
  get '/api/v1/books' do  
    example_request 'all books' do  
      expect(status).to eq(200)  
    end  
  end
   
  post '/api/v1/books' do  
    parameter :title, scope: :book  
    parameter :description, scope: :book  
    let(:title) { Faker::Book.title }  
    let(:description) { Faker::ChuckNorris.fact }  
  
    example_request 'create a book' do  
      expect(status).to eq(200)  
    end
  end  
end

Generate your documentation with:

rake docs:generate

Now you can find your documentation here doc/api/index.html.

It looks like this:

You can find more info about rspec_api_documentation on this page

License

Timebot is Copyright © 2015-2019 Codica. It is released under the MIT License.

About Codica

Codica logo

The names and logos for Codica are trademarks of Codica.

We love open source software! See our other projects or hire us to design, develop, and grow your product.