STANBOL-15, RESTful API documentation generation - prototype based on integration tests

[Bertrand Delacretaz <bd...@apache.org>]

Hi,

I just committed some prototype code that generates documentation for
our RESTful APIs based on enhanced integration tests.

Output format is rough for now, but that's easy to fix, using velocity
or other templates for example. Maybe generate Markdown text that can
go straight into our website.

Here's an example enhanced test (see [1] for complete test class):

    @Test
    public void testSimpleEnhancement() throws Exception {
        executor.execute(
            builder.buildPostRequest("/engines")
            .withHeader("Accept","text/rdf+nt")
            .withContent("The Stanbol enhancer can detect famous
cities such as Paris and people such as Bob Marley.")
        )
        .assertStatus(200)
        .assertContentRegexp(
                "http://purl.org/dc/terms/creator.*MetaxaEngine",
                "http://purl.org/dc/terms/creator.*LangIdEnhancementEngine",
                "http://purl.org/dc/terms/language.*en",
                "http://purl.org/dc/terms/creator.*LocationEnhancementEngine",
                "http://fise.iks-project.eu/ontology/entity-label.*Paris",

"http://purl.org/dc/terms/creator.*NamedEntityExtractionEnhancementEngine",
                "http://fise.iks-project.eu/ontology/entity-label.*Bob Marley"
                )
        .generateDocumentation(
                documentor,
                "title",
                "Stateless text analysis",
                "description",
                "A POST request to ${request.path} (TODO should be
replaced by actual path) returns triples representing enhancements "
                + " of the POSTed text. Output format is defined by
the Accept header."
        );
    }

Basically, you just add a call to .generateDocumentation() with some
metadata that describes the request.

The generator outputs something like (see [2] for full output):

=== Stateless text analysis ===
A POST request to ${request.path} (TODO should be replaced by actual
path) returns triples representing enhancements  of the POSTed text.
Output format is defined by the Accept header.

=== REQUEST ===
Method: POST
URI: http://localhost:58539/engines
Headers:
Accept:text/rdf+nt
Content-Type:text/plain; charset=UTF-8
Content:
The Stanbol enhancer can detect famous cities such as Paris and people
such as Bob Marley.

=== RESPONSE ===
Content-Type:text/rdf+nt
Content:
<urn:enhancement-f4b51f1e-fcae-3e14-8919-9fcc19be95c6>
<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>
<http://fise.iks-project.eu/ontology/Enhancement> .
...


I think this could be a good way of documenting our RESTful API, and
making sure that documentation stays up to date.
WDYT?

-Bertrand

[1]  http://svn.apache.org/repos/asf/incubator/stanbol/trunk/enhancer/integration-tests/src/test/java/org/apache/stanbol/enhancer/it/StatelessEngineTest.java
[2] https://issues.apache.org/jira/secure/attachment/12470596/org.apache.stanbol.enhancer.it.StatelessEngineTest.txt

Re: STANBOL-15, RESTful API documentation generation - prototype based on integration tests

[Olivier Grisel <ol...@ensta.org>]

2011/2/8 Bertrand Delacretaz <bd...@apache.org>:
>
> I think this could be a good way of documenting our RESTful API, and
> making sure that documentation stays up to date.
> WDYT?

That sounds great. Markdown rendering to be dumped into the svn folder
of the site would be really great. Also HTML outpout (to be included
in the server build to fill up the inline "REST API" documentation of
the Web UI would be good too.

-- 
Olivier
http://twitter.com/ogrisel - http://github.com/ogrisel