Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jejacks0n/apitome

Apitome: /iˈpitəmē/ An API documentation presentation layer for RSpec API Documentation output.
https://github.com/jejacks0n/apitome

documentation rad rails rspec

Last synced: 3 days ago
JSON representation

Apitome: /iˈpitəmē/ An API documentation presentation layer for RSpec API Documentation output.

Awesome Lists containing this project

README 

        
Apitome

=======



[![Gem Version](https://img.shields.io/gem/v/apitome.svg)](https://rubygems.org/gems/apitome)

[![Build Status](https://img.shields.io/travis/jejacks0n/apitome.svg)](https://travis-ci.org/jejacks0n/apitome)

[![Maintainability](https://api.codeclimate.com/v1/badges/eb8dd1c22f1da11b6c02/maintainability)](https://codeclimate.com/github/jejacks0n/apitome/maintainability)

[![Test Coverage](https://api.codeclimate.com/v1/badges/eb8dd1c22f1da11b6c02/test_coverage)](https://codeclimate.com/github/jejacks0n/apitome/test_coverage)

[![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)



Apitome is a API documentation tool for Rails built on top of the great RSpec DSL included in

[rspec_api_documentation](https://github.com/zipmark/rspec_api_documentation) (RAD). It's designed to display the

documentation generated by RAD in either a single page, or on individual pages, and uses Bootstrap for most of the basic

styling and [highlight.js](https://github.com/isagalaev/highlight.js) for code highlighting.



You can provide a markdown file that will be displayed as the README page, and by taking advantage of its modular view

structure you can override any number of views and partials to customize the output. You can also specify custom css and

javascript if you want to do fancier things or change how it looks.



## Installation

Add it to your Gemfile.



```ruby

gem "apitome"

```



Optionally run the install generator to get the initializer and an initial readme file (doc/api.md).



```

rails generate apitome:install

```



You can get the assets installed using the generator by providing a `--assets` flag.



Update your `spec_helper.rb` to adjust how RAD outputs its results -- Apitome reads these JSON files to generate the

documentation.



```ruby

RspecApiDocumentation.configure do |config|

  config.format = :json

end

```



## Usage

You can view your documentation at the default `api/docs` route.



## Configuration

After installation, your app will have an apitome initializer (app/config/initializers/apitome.rb). You will find the

following parameters that can be used to customize apitome. Note: Restart rails after changing any of these parameters.





 mount_at 




  This determines where the Apitome routes will be mounted. Changing this to "/api/documentation" for instance would

  allow you to browse to http://localhost:3000/api/documentation to see your api documentation. Set to nil and mount

  it yourself if you need to.

  


  default: "/api/docs"




 root 




  This defaults to Rails.root if left nil. If you're providing documentation for an engine using a dummy application

  it can be useful to set this to your engines root. (E.g. Application::Engine.root)

  


  default: nil




 doc_path 




  This is where rspec_api_documentation outputs the JSON files. This is configurable within RAD, and so is

  configurable here.

  


  default: "doc/api"




 parent_controller 




  Set the parent controller that Apitome::DocsController will inherit from. Useful if you want to use a custom

  before_action for instance.

  


  default: "ActionController::Base"




 title 




  The title of the documentation -- If your project has a name, you'll want to put it here.

  


  default: "Apitome Documentation"




 layout 




  The main layout view for all documentation pages. By default this is pretty basic, but you may want to use your own

  application layout.

  


  default: "apitome/application"




 code_theme 




  We're using [highlight.js](https://github.com/isagalaev/highlight.js) for code highlighting, and it comes with some

  great themes. You can check [here for themes](http://softwaremaniacs.org/media/soft/highlight/test.html), and enter

  the theme as lowercase/underscore.

  


  default: "default"




 css_override 




  This allows you to override the css manually. You typically want to require apitome/application within the

  override, but if you want to override it entirely you can do so.

  


  default: nil




 js_override 




  This allows you to override the javascript manually. You typically want to require apitome/application within the

  override, but if you want to override it entirely you can do so.

  


  default: nil




 readme 




  You can provide a "README" style markdown file for the documentation, which is a useful place to include general

  information. This path is relative to your doc_path configuration.

  


  default: "../api.md"




 single_page 




  Apitome can render the documentation into a single page that uses scrollspy, or it can render the documentation on

  individual pages on demand. This allows you to specify which one you want, as a single page may impact performance.

  


  default: true




 url_formatter 




  You can specify how urls are formatted using a Proc or other callable object.  Your proc will be called with a

  resource name or link, giving you the opportunity to modify it as necessary for in the documentation url.

  


  default: -> (str) { str.gsub(/\.json$/, '').underscore.gsub(/[^0-9a-z]+/i, '-') }




 remote_url 




  You can setup the docs to be loaded from a remote URL if they are not available in the application environment. This

  URL is used as the base location and should be set to where the readme is located. If left nil, local is assumed.

  


  default: nil




 http_basic_authentication 




  If using remote urls you can fetch the remote docs using HTTP Basic Authentication by configuring this to be an

  array of the user and password. (E.g. ['user', 'password'])

  


  default: nil




 precompile_assets 




  By default all assets that ship with this library are precompiled by the asset pipeline. If you would prefer to

  control this yourself, you can disable it by changing this to false.

  


  default: true




 simulated_response 




  If simulated_response is disabled you can hide the "Simulated Response" links.

  


  default: true




When you install Apitime an initializer file (app/config/initializers/apitome.rb) is generated that contains good

documentation for each configuration directive. Otherwise you can get a refresher by checking the

[Apitome Configuration](https://github.com/modeset/apitome/wiki/Apitome-Configuration) article.



## Customization

You can put custom views and partials in your own `views/apitome/docs` -- check

[here for examples](https://github.com/jejacks0n/apitome/tree/master/app/views/apitome/docs). You can put any

partial in your own path and they will be overridden.



Additional customization can come in the form of providing custom css and javascript. You can do this by creating the

files you want (that often times require the default assets in the gem), and then configure Apitome to use those instead

of the defaults.



## License

Licensed under the [MIT License](http://creativecommons.org/licenses/MIT/)



Copyright 2016 [jejacks0n](https://github.com/jejacks0n)



## Make Code Not War