Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Autodoc

CircleCI Gem Version

Generate documentation from your rack application & request-spec.

Installation

gem "autodoc", group: :test

If you want to generate toc_html, you should install redcarpet gem (optional).

gem "redcarpet", group: :test

Usage

Run rspec with AUTODOC=1 to generate documents for your request-specs tagged with :autodoc.
example: Autodoc generates doc/recipes.md and doc/toc.md from spec/requests/recipes_spec.rb.

# shell-command
AUTODOC=1 rspec

Examples

For any Rack application with rack-test

# spec/requests/entries_spec.rb
describe "Entries" do
  include Rack::Test::Methods

  let(:app) do
    MyRackApplication
  end

  describe "GET /entries", autodoc: true do
    it "returns entries" do
      get "/entries"
      last_response.status.should == 200
    end
  end
end

For Rails application with rspec-rails

# spec/requests/recipes_spec.rb
describe "Recipes" do
  describe "POST /recipes", autodoc: true do
    it "creates a new recipe" do
      post "/recipes", name: "alice", type: 1
      response.status.should == 201
    end
  end
end

Custom description

You can write more detailed descriptions with let(:description).

describe "Recipes" do
  describe "PUT /recipes/:id", autodoc: true do
    let(:description) do
      "Updates a recipe. `name` parameter is required."
    end

    it "updates a recipe" do
      put "/recipes/#{recipe.id}", name: "Bob"
      response.status.should == 204
    end
  end
end

Configuration

You can configure Autodoc.configuration to change its behavior:

  • path - [String] location to put files (default: ./doc)
  • suppressed_request_header - [Strings] filtered request header keys
  • suppressed_response_header - [Strings] filtered response header keys
  • template - [String] ERB template for each document (default: document.md.erb)
  • toc_template - [String] ERB template for ToC (default: toc.md.erb)
  • toc - [Boolean] whether to generate toc.md (default: false)
  • toc_html_template - [String] ERB template for html ToC (default: toc.html.erb)
  • toc_html - [Boolean] whether to generate toc.html - a single page documentation with a toc (default: false)
  • document_path_from_example - [Proc] specify a Proc to change the naming rule of document file paths
Autodoc.configuration.path = "doc/api"
Autodoc.configuration.toc = true
Autodoc.configuration.toc_html = true
Autodoc.configuration.template = File.read(File.expand_path("../autodoc/templates/document.md.erb", __FILE__))
Autodoc.configuration.document_path_from_example = -> (example) do
  example.file_path.gsub(%r<\./spec/requests/api/(.+)_spec\.rb>, '\1.md')
end

WeakParameters integration

If your app uses WeakParameters to define parameters schema in your controller, autodoc scans them and provides ### Parameters section to generated docs.

class RecipesController < ApplicationController
  validates :create do
    string :name, required: true, except: ["charlie", "dave"]
    integer :type, only: 1..3
  end

About

Generate documentation from your rack application & request-spec.

Topics

Resources

License

Packages

No packages published
You can’t perform that action at this time.