washout_builder <img src=“https://travis-ci.org/bogdanRada/washout_builder.png?branch=master,develop” /> <img src=“https://badge.fury.io/rb/washout_builder.png” alt=“Gem Version” />
Overview
WashOutBuilder is a Soap Service Documentation generator (extends WashOut github.com/inossidabile/wash_out/)
The way WashOut is used is not modified, it just extends its functionality by generating html documentation to your services that you write
Features
-
Provides way of seeing the available services with links to documentation, endpoint and namespace
-
Provides a human-readable HTML documentation generated for each service that you write
Screenshots (just an example)
Requirements
Compatibility
Rails >3.0 only. MRI 1.9, 2.0, JRuby (–1.9).
Ruby 1.8 is not officially supported since 0.5.3. We will accept further compatibilty pull-requests but no upcoming versions will be tested against it.
Rubinius support temporarily dropped since 0.6.2 due to Rails 4 incompatibility.
Setup
Type the following from the command line to install:
gem install washout_builder
Add the following to your Gemfile:
gem "washout_builder"
it will automatically install also wash_out
gem that is currently used
Or if you want this to be available only in development mode , you can do something like this inside the Gemfile:
gem 'wash_out' # The WashOut gem would be used also in production
group :development, :test do
gem 'washout_builder' # only available in development mode.
end
Please read release details if you are upgrading. We break backward compatibility between large ticks but you can expect it to be specified at release notes.
Usage
The way soap_actions, or reusable types are defined or how the configuration is made using WashOut(github.com/inossidabile/wash_out) haven’t changed You can still do everything that gem does .
In order to see the documentation you must write something like this in the routes (exactly like you would do when using only WashOut)
In the following file config/routes.rb
you can put this configuration
WashOutSample::Application.routes.draw do
wash_out :rumbas
wash_out :my_other_service
end
mount WashoutBuilder::Engine => "/washout"
You can access the url /washout
and you will see a list with available services ( in our case there are only two : The RumbasController and MyOtherServiceController) with links to their documentation and where you can find the WSDL.
If you want to access directly the hml documentation that was generated for RumbasController you can do that by accessing url /rumbas/doc
And the WSDL will be available at /rumbas/wsdl
When specifying the soap_service you can also pass a option for description . Here is an example
soap_service namespace: "http://my.app.com/my_service/wsdl",
:description => "here goes some description for your service"
When specifying the soap_action you can also pass a option for description and a list of exceptions(need to be classes) that the method can raise at a certain moment.
Here is an example :
soap_action "find",
:args => {:number => :integer} ,
:return => :boolean,
:raises => [MyCustomSoapError, MyOtherCustomSoapError ] ,
:description => "some description about this method to show in the documentation"
The exception classes used must inherit from WashOut::Dispatcher::SOAPError
, which has by default a error code and a message as attributes but you can extend it by adding more attributes to your own custom class.
The WashOut::SoapError now includes Virtus.model from virtus
gem. This way you can add attributes like this:
class MyCustomSoapError < WashOut::Dispatcher::SOAPError
attribute :custom_attribute, String
attribute :other_custom_attribute, Integer
end
You can also specify complex types like this:
class MyCustomSoapError < WashOut::Dispatcher::SOAPError
attribute :errors,Array[Integer]
attribute :custom, Array[MyCustomModel]
attribute :custom2, MyCustomModel
end
The class MyCustomModel must include Virtus.model
or Virtus.value_object
or it must include at least one module that includes Virtus.module
if you want it to show up in the documentation! Please checkout Gem[https://github.com/solnic/virtus] for further documentation!
You can also use aggregation with another fault class exception like this:
class MyCustomSoapError < WashOut::Dispatcher::SOAPError
attribute :errors, Array[MyOtherCustomSoapError]
end
And you can also use inheritance between custom exception classes like this:
class MySecondCustomSoapError < MyCustomSoapError
atribute :option , String
end
And you will see in the documentation that the class MySecondCustomSoapError
will extend MyCustomSoapError
Testing
To test, do the following:
-
cd to the gem root.
-
bundle install
-
bundle exec rake
Contributions
Please log all feedback/issues via GitHub Issues. Thanks.
Contributing to washout_builder
-
Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet.
-
Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it.
-
Fork the project.
-
Start a feature/bugfix branch.
-
Commit and push until you are happy with your contribution.
-
Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.
-
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
Copyright
Copyright © 2013 bogdanRada. See LICENSE.txt for further details.