Apitome: /iˈpitəmē/ An API documentation presentation layer for RSpec API Documentation output.
Apitome is a API documentation tool for Rails built on top of the great RSpec DSL included in 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 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.
Add it to your Gemfile.
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.
RspecApiDocumentation.configure do |config|
config.format = :json
end
You can view your documentation at the default api/docs
route.
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.
"/api/docs"
Application::Engine.root
)
nil
"doc/api"
before_action
for instance.
"ActionController::Base"
"Apitome Documentation"
"apitome/application"
"default"
apitome/application
within the
override, but if you want to override it entirely you can do so.
nil
apitome/application
within the
override, but if you want to override it entirely you can do so.
nil
"../api.md"
true
-> (str) { str.gsub(/\.json$/, '').underscore.gsub(/[^0-9a-z]+/i, '-') }
nil
['user', 'password']
)
nil
true
simulated_response
is disabled you can hide the "Simulated Response" links.
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 article.
You can put custom views and partials in your own views/apitome/docs
-- check
here for examples. 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.
Licensed under the MIT License
Copyright 2016 jejacks0n