Many software tools generate web service documentation from a machine-readable description of an API (e.g. from WSDL, WADL, or Swagger), but often the results are not very human-friendly. We. Deserve. Better.
The Expo specification was created with the goal of teaching machines to understand human-generated API documentation rather than the other way around. This allows the machines to do what they're good at (executing test cases, automated validation, interactive stubs, live demos) and leaves the writing and presentation to us humans.
High-quality API documentation is usually structured around well-crafted examples. Examples are the best way to show what a web service does and how it helps solve a particular problem. API examples are also fairly simple for a machine to recognize and leverage for its own purposes. There are many possibilities:
- Want to verify that a system does what you say it does? Have a machine run the examples as test cases. Do this as part of your Continuous Integration process to guarantee the docs and implementation are in sync.
- Want to let customers poke around and explore your API? Have a machine convert the documented examples into a Postman collection or SoapUI project for humans to play with.
- Gathering requirements? Let your documentation serve double-duty as acceptance criteria for your implementation.
- Need a stub service to build against? Use the web service documentation to automatically generate a stub implementation with canned responses pulled straight from the API docs.
Most API documents are already using examples to describe how the service works. Look at the Twitter API, GitHub API, and Facebook API: they all feature prominent example requests and responses. The Expo spec just defines how machines should process those kinds human-targeted documents.
This repository specifies how to interpret HTML documents written by humans and extract API examples in a JSON format that is easily understood by machines. It is meant to be mostly compatible with the de facto writing conventions already used by API documentation authors.
The spec itself is a set of declarative examples in spec.txt. This is basically a Markdown file, with input/output examples written in sequence:
```html
HTML source
```
```json
expected JSON output
```