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
