Rpdoc

Rpdoc is a simple Postman API documentation tool, which transforms RSpec examples to Postman collection (with json files in Postman data format stored locally).

Benefits

• Save time for generating Postman examples manually.
• Improve maintainability of your API documentation (easy to create/update and put it into version control with CI/CD).

Installation

Add rpdoc to your application's Gemfile:

gem 'rpdoc'

And then install the gem:

$ bundle install

Configuration

Rpdoc should be configured manually if you want to automatically push your collection to the Postman server.

You can also run the following command to generate the configuration file for your Rails application.

$ rails g rpdoc:install

Rpdoc can be configured by the following options.

Rpdoc.configure do |config|

  # (Optional) You can disable rpdoc generation process manually.
  config.rpdoc_enable = true

  # (Optional) Apikey for your Postman account, used if want to push collection to the Postman server.
  config.postman_apikey = 'postman_apikey'

  # (Optional) Workspace that your collection will be pushed to. Default your account's personal workspace. 
  config.collection_workspace = 'collection_workspace'

  # (Optional) Your existing collection uid. Will update it when using :push_and_update push strategy.
  config.collection_uid = 'collection_uid'

  # (Optional) Collection name.
  config.collection_name = 'Rpdoc'

  # (Optional) Your Rails server API host.
  config.rspec_server_host = '{{server_host}}'

  # (Optional) Since Rspec generates many noisy headers, you can filter them.
  config.rspec_request_allow_headers = ['User-Agent', 'Content-Type', 'Authorization']

  # (Optional) Folder that Rpdoc use for json data generation and save.
  config.rpdoc_root = 'rpdoc'

  # (Optional) Filename to store RSpec request json data.
  config.rpdoc_request_filename = 'request.json'

  # (Optional) Filename to store Postman description markdown data.
  config.rpdoc_description_filename = 'description.md'

  # (Optional) Filename to store RSpec collection json data.
  config.rpdoc_collection_filename = 'collection.json'

  # (Optional) Auto push collection to Postman server or not.
  config.rpdoc_auto_push = false

  # (Optional) Auto push strategy, including :push_and_create and :push_and_update
  config.rpdoc_auto_push_strategy = :push_and_create
end

Usage

Rpdoc only supports RSpec examples with request type.

1. Include shared_context in your spec to make Rpdoc identify which examples to transform. ruby RSpec.describe 'POST /api/v1/books', type: :request do include_context 'rpdoc' ... end

2. Customiz your example metdata to generate collection data in your preferenced format.

   it 'should return 200' do |example|
       # Request identifier.
       # Default is `controller.action_name` 
       example.metadata[:rpdoc_action_key] = 'create'
   
       # Request name shown in Postman collection.
       # Default is `controller.action_name` 
       example.metadata[:rpdoc_action_name] = 'Create a book.'
   
       # Example identifier.
       # Default is `controller.action_name` 
       example.metadata[:rpdoc_example_key] = "create_200"
   
       # Example name shown in Postman colleciotn. 
       # Default is `example.metadata[:description]`
       example.metadata[:rpdoc_example_name] = "Create a book success."
   
       # Example location shown in Postman collection.
       # Default is `controller.controller_path.split('/')`
       example.metadata[:rpdoc_example_folders] = ['v1', 'books']
   
       # Skip this example if you have already included shared context in the spec.
       # Default is `false`.
       example.metadata[:rpdoc_skip] = false
   end
   

3. Run your specs, generate data in Postman format, and push your collection to the Postman server.

   $ rspec
   

If you want to disable Rpdoc generation process manually, you can either set rpdoc_enable = false in configuration or just pass environment variable to rspec.

   $ RPDOC_ENABLE=false rspec

1. You can write description for your Postman collection by creating markdown files (named description.md) and putting each of them in corresponding location under rpdoc folder.

License

The gem is available as open source under the terms of the MIT License.