API tool
API reference generator for Swagger and RAML.
This module generates live documentation from your HTTP API (source code).
screenshots
swagger
raml
dependency
<dependency>
<groupId>org.jooby</groupId>
<artifactId>jooby-apitool</artifactId>
<version>1.6.6</version>
</dependency>
usage
{
use(new ApiTool()
.swagger("/swagger")
.raml("/raml")
);
}
Those lines export your API to Swagger, RAML or ReDoc.
example
Suppose you have a Pet API like:
{
/**
*
* Everything about your Pets.
*/
path("/api/pets", () -> {
/**
*
* List pets ordered by name.
*
* @param start Start offset, useful for paging. Default is ```0```.
* @param max Max page size, useful for paging. Default is ```200```.
* @return Pets ordered by name.
*/
get(req -> {
int start = req.param("start").intValue(0);
int max = req.param("max").intValue(200);
DB db = req.require(DB.class);
List<Pet> pets = db.findAll(Pet.class, start, max);
return pets;
});
/**
*
* Find pet by ID
* @param id Pet ID.
* @return Returns ```200``` with a single pet or ```404```
*/
get("/:id",req -> {
int id = req.param("id").intValue();
DB db = req.require(DB.class);
Pet pet = db.find(Pet.class, id);
return pet;
});
/**
*
* Add a new pet to the store.
* @param body Pet object that needs to be added to the store.
* @return Returns a saved pet.
*/
post(req -> {
Pet pet = req.body().to(Pet.class);
DB db = req.require(DB.class);
db.save(pet);
return pet;
});
/**
*
* Update an existing pet.
* @param body Pet object that needs to be updated.
* @return Returns a saved pet.
*/
put(req -> {
Pet pet = req.body().to(Pet.class);
DB db = req.require(DB.class);
db.save(pet);
return pet;
});
/**
*
* Deletes a pet by ID.
* @param id Pet ID.
* @return A ```204```
*/
delete("/:id",req -> {
int id = req.param("id").intValue();
DB db = req.require(DB.class);
db.delete(Pet.class, id);
return Results.noContent();
});
});
/**
*
* Install API Doc and export your HTTP API:
*/
use(new ApiTool()
.swagger("/swagger")
.raml("/raml")
);
}
The ApiTool module automatically exports your application to Swagger and RAML.
Works for MVC routes and Kotlin.
redoc
ReDoc example:
{
use(new ApiTool()
.redoc()
)
}
Or if you want to keep Swagger UI and ReDoc:
{
use(new ApiTool()
.swagger(new Options("/swagger")
.redoc()
)
)
}
keep documentation
The ApiTool module parses documentation from source code. It works well as long as the source code is present, but it won’t work after you deploy your application.
To fix this we provide a Maven and Gradle tasks that process your API at build time and keep the documentation available for later usage.
maven plugin
Go to the plugins section of your pom.xml and add these lines:
<plugin>
<groupId>org.jooby</groupId>
<artifactId>jooby-maven-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>apitool</goal>
</goals>
</execution>
</executions>
</plugin>
Now, compile your application the apitool plugin generates a .json file for your API.
gradle task
Go to build.gradle and add these lines:
buildscript {
dependencies {
classpath group: 'org.jooby', name: 'jooby-gradle-plugin', version: '1.6.6'
}
}
apply plugin: 'jooby'
Then run:
joobyApiTool
options
filter
The filter option controls what routes are exported.
{
use(new ApiTool()
// Keep /api/* routes:
.filter(route -> route.pattern().startWiths("/api/")
);
}
disable try it
Disable the tryIt button in Swagger or RAML.
{
use(new ApiTool()
.disableTryIt()
);
}
disable UI
Disable UI for Swagger or RAML.
{
use(new ApiTool()
.disableUI()
);
}
theme
Set the default theme for Swagger or RAML.
{
use(new ApiTool()
.raml(
new Options("/raml")
.theme("dark")
)
.swagger(
new Options("/swagger")
.theme("muted")
)
);
}
Themes can set at runtime too via theme query parameter:
/swagger?theme=material
/raml?theme=dark
Complete list of Swagger theme are available here.
Raml comes with only two themes: light and dark.
advanced usage
Sometimes the ApiTool module doesn’t generate correct metadata like type, names, documentation, etc. When that happens you need to manually fix/provide metadata.
{
use(new ApiTool()
.modify(r -> r.pattern().equals("/api/pet/{id}", route -> {
// Fix java doc for id parameter
route.param("id", param -> {
param.description("Fixing doc for ID");
});
// Set response type
route.response()
.type(Pet.class);
});
);
}
}
It is possible to customize Swagger/RAML objects:
{
use(new ApiTool()
.swagger(swagger -> {
// Modify swagger resources.
...
})
.raml(raml -> {
// Modify raml resources.
...
});
);
}
}
This option is required when you want to customize/complement Swagger/RAML objects.
For Swagger you can annotated your controller methods with ApiOperation and/or ApiResponse annotations. These annotations modifies the Swagger output.
starter project
We do provide an apitool-starter project.
That’s all folks!!