Home

Fictium

A gem to power your RSpec tests and generate documentation with minimal writting.

Why this gem?

This gem was born as a replacement for Dictum, mostly because Dictum returns only HTML output and Wolox decided to adopt Swagger as their default documentation format.

This provides a really easy RSpec + Swagger integration, allowing minimal changes to your test to automatically generate documentation.

But this gem doesn't require RSpec nor Swagger, you may opt to use another test framework or exporting format (in the future).

Installing

General Installation Steps

• Install this gem (gem install 'fictium') or add it to your gemfile:

group :development, :test do
  gem 'fictium'
end

You are mostly done, now each framework requires specific install instructions.

Steps for RSpec

Inside your spec_helper.rb (or rails_helper.rb):

# Require the RSpec official implementation:
require 'fictium/rspec'

# Add some default configurations:

Fictium.configure do |config|
  # You will require to configure the fixture path, if you want to use fixtures
  config.fixture_path = File.join(__dir__, 'support', 'docs')
end

Check out more details of the RSpec integration here.

Configuration

For configuration options, just do Fictium.configure(&block) to setup your configurations:

For example:

Fictium.configure do |config|
  config.fixture_path = File.join(__dir__, 'support', 'docs')

  config.info.title = 'Some new title'
  config.terms_of_service = 'http://url.to.terms.of.service'
end

You can also check the spec folder, spec_helper.rb has a basic Fictium configuration for testig.

Read below about configurations available:

General configuration

name	description
exporters	An array of document exporters. Any object with a export(document) method, is a valid exporter.
pretty_print	If true, it will print your documentation on a pretty format. (Enabled by default)

API information

All this information is under the config.info object. Handles mostly API information

name	description
title	The title of the API, should be changed to the name of your API.
description	A summary of your API. This could be omitted.
terms_of_service	An URL to your terms of service for your API.
contract	A hash containing a Swagger contract
license	The license of the API. It must be a hash with two keys: url, and name. Both values should be strings.
version	The version of your API, it is 0.1.0 by default.
export_path	The export path for your documentation, by default is the doc folder.

Comment auto generation

name	description
summary_format	A method when called, it returns a default summary for a resource.
default_action_descriptors	a hash containing a list of functions. Each pair must be in the format of action_name => lambda/proc/method. This will be called as a default description for actions like index, show, create, destroy and update. You can add more, if your application has common actions across the API. The method can only require the action as `-> {
unknown_action_descriptor	When the descriptor is not found, this proc will be called instead. The same rules used in the action descriptor applies with this method.
default_subject	The default subject used by the summary on each endpoint, by default is "This endpoint"

Response/Request configurations

name	description
ignored_header_values	Any header key added here, will be ignored from the documentation. (The list only contains lower case versions of the headers.
ignored_header_groups	Similar to the previous one, but this instead will ignore any header starting with the following text. This is used because Rails tend to add a lot of headers, starting with rack.*, etc.
default_response_content_type	The default content type returned for responses when the text is empty. by default is text/plain

API Blueprint Configurations

This configurations are inside the Fictium.configuration.api_blueprint.* configuration.

name	description
host	The host where your API is published.
resources_group_name	The header you want into your resource list.
footer_header	The header you want to your footer. It accepts markdown.
api_version_formatter	A lambda, when given a semantic versioning version, it returns how it should be printed.
terms_of_service_formatter	A lambda, with how to format your terms of service.
license_formatter	A lambda, with the format you want for your license.

Postman Configurations

This configurations are inside the Fictium.configuration.postman.* configuration.

name	description
id	Your collection ID, usually an UUID4. But can be any valid string.
api_url	How to display your base URL, by default is {{API_URL}} to use environment variables.
default_status_names	A hash handling status names for common responses. for example, 201 could be CREATED.
unknown_status_name	A lambda, where it gives the http status code and the example. It shows which name it should have.
example_formatter	A lambda, when called with a status code and an example, it returns the title of the example case.