This gem is a documentation helper. The goal of this gem is, by adding small modifications into your existing tests, you can then transform it into easy REST documentation.
For the initial release, the support is focused explicitly on generating documentation from RSpec tests, and generate an OpenAPI V3.0.2 Document.
The current Gem version allows to export into the following formats:
| Exporter | Class name | Notes |
|---|---|---|
| OpenApi 3.0 | Fictium::OpenApi::V3Exporter |
The default exporter for the current Gem version. It doesn't include 100% of the OpenAPI specification, but it works for the most common use cases. It's the format Swagger uses for documentation. |
| API Blueprint | Fictium::ApiBlueprintExporter |
Used by Apiary. A superset of Markdown with special keywords and controls. |
| Postman Collection | Fictium::Postman::V2Exporter |
Export your test as a Postman collection for easy creation of mock APIs and quick debugging. |
Future versions may provide:
- OpenApi 1.0 and 2.0
- Custom HTML exporter
Add this line to your application's Gemfile:
gem 'fictium'And then execute:
$ bundle
Or install it yourself as:
$ gem install fictium
Fictium is a Gem to generate documentation from your tests. Instead of you having to write entirely new tests, the goal of this gem is to provide easy to use, tags and annotations on your existing tests.
Fictium is closely tied to RSpec and Rails, but it's developed in a way to support more testing suites or engines in future versions.
The primary goal is for generating OpenAPI Documentation, but, just like with RSpec, future versions may provide other output types.
Because this GEM is used to represent REST APIs, this gem, provides some common objects, which are used as a documentation naming scheme. They are independant from the actual documentation format, so each exporter should transform this abstract representation into the actual document representation.
The base object, is de Fictium::Document. This class represent your whole API. One is created when the testing starts.
The document, then is divided in resources. The class Fictium::Resource is the one dedicated to handle them. A resource is a Rest object, for example, Posts, Users or Tags.
Each resource is sub divided in actions, Fictium::Action. Actions are enpoints associated with a REST method.
This gem attemps to complete the documentation for you, so you don't have to constantly document it yourself. To configure how this gem completes your documentation, you have some configurations available here.
Just require 'fictium/rspec' in your rails helper and your RSpec test will include everything you need to work in your environment.
(be aware, the current version requires Rails to be previously loaded to work).
At any test of type: :controller, you can just add the following helpers:
describe PostsController do
describe action 'GET #index' do
describe example 'without errors' do
default_example # You can select an example to be marked as default in your action
before do
get :index
end
# ... your tests
end
end
endThe idea, is that your controller has actions, and each actions has examples.
You can, for now, check spec/controllers at this repository to
You can deeply customize your endpoints using RSpec. Check out details here.
After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/fictium. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.
This gem is developed by Wolox.
Maintainers: Ramiro Rojo Contributors: None (for now...)
Everyone interacting in the Fictium project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent