mjl > sherpa > api documentation
Intro | API documentation | Consuming | Specification | Implementations | FAQ | Why

Why documentation?

Documentation is required to use an API properly. It's important, but it takes a time to write, easily gets out of sync with the code, and requires effort to publish.

Not with Sherpa. Of course, you still need to write documentation. But it is kept right with your code, easy to keep up to date. You don't need complicated tools to generate documentation and host documentation. That's all provided automatically by the sherpa library for your programming language.

Example

An example of sherpa documentation can be found at:

sherpadoc.org/#https://www.sherpadoc.org/example/

How does it work?

You write implementations for your API functions. And write comments in your code to document functions and types. Then you run the documentation-generating tool for your programming language. For the Go implementation this is "sherpadoc". It reads your code, finds the exported functions and types and associated comments, and generates a JSON file containing documentation. You pass that file to the sherpa server library in your application. When the sherpa function _docs is called, the documentation JSON is returned.

How do I read documentation?

Using sherpaweb, a simple web app that calls the _docs function, and displays the documentation. Sherpaweb also lets you call functions with parameters you specify, displaying the return values.

Use the public instance of sherpaweb:

sherpadoc.org

Note that your browser reads and renders documentation, so you can use the public sherpaweb for your internal/local API's.

Running your own sherpaweb is also easy: Use one of the binaries below, or compile from source.

Download

The following binaries are available:

Sherpaweb is open source, you can find it at bitbucket.org/mjl/sherpaweb.