Download - Streamlined Geek Talk
Streamlined Geek Talk Web Services APIs and
Always Up-to-Date Documentation
with Rails and Cucumber
by Sarah Allen and Wolfram Arnold
multiple clients, multiple developers
Use cases
• Corporate teams– communication between developers– outsourced development– documenting an open API
• Open source– documenting API– interface stability
Always up-to-date Documentation
spec = test = doc
Server Engineerwrites code
Server Engineerwrites code
CI Pass?Client Engineerwrites code
Client Engineerwrites code
Server Engineerwrites scenarioServer Engineerwrites scenario
Covered?
Feature DocsFeature Docs
New Client App Legacy Code
Target Workflow
How we made it happen
• Pre-existing codebase• Generate HTTP traffic logs from client apps• Wrote cucumber features for each use case
Tools• Cucumber BDD framework – http://cukes.info/– http://wiki.github.com/aslakhellesoy/cucumber
• Webrat (gem)• Using DB fixtures in cucumber– http://wiki.github.com/aslakhellesoy/cucumber/fixtures
• Using XML fixtures to compare server response– xmlsubsetmatcher library
• Continuous integration – hudson, cruisecontrol.rb, integrity
• Example:– http://github.com/mightyverse/cucumber_xml
Rails Web Services
app/controllers/projects_controller.rb
respond_to do |format| format.html
# views/projects/index.html.erb format.xml
# views/projects/index.xml.builderend
Rails Web Servicesapp/views/projects/index.xml.builder
xml.instruct!xml.projects do xml.total @projects.length @projects.each do |project| xml.project do xml.name project.name xml.notes project.notes end endend
Feature Scenarios
Feature: Project XML API In order to read project data data As a device or client application using the XML REST interface I want to make GET requests to the /projects URL
Scenario: Get Medium When I send an XML GET to /projects.xml Then I get a 200 (success) status result And the response header Content-Type matches application/xml And the response should be a superset of the file: "xml/projects.xml"
Workflow
• Publish doc from source repository• Continuous integration run feature scenarios
on every checkin• All engineers have access to CI• Separate test and production environments
Results
Surfaces undocumented requirements
Highlights use of undocumented API’s
Software works well
Always up-to-date Documentation
spec = test = doc
www.mightyverse.com
Wolfram Arnold rubyfocus.biz
Sarah Allenultrasaurus.com