public class ApiTool extends Object implements Jooby.Module
Automatically export your HTTP API to open standards like Swagger and RAML.
This module generates live documentation from your HTTP API.
{
use(new ApiTool()
.swagger("/swagger")
.raml("/raml")
);
}
Those lines export your API to Swagger and RAML.
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.
The ApiTool module parse 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.
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 will generates a .json file for your API.
Go to build.gradle and add these lines:
buildscript {
dependencies {
classpath group: 'org.jooby', name: 'jooby-gradle-plugin', version: '1.1.3'
}
}
apply plugin: 'jooby'
Then run:
joobyApiTool
There are a couple of options that control what is exposed as well as how do we export.
The filter option controls what routes are exported.
{
use(new ApiTool()
// Keep /api/* routes:
.filter(route -> route.pattern().startWiths("/api/")
);
}
Disable the tryIt button in Swagger or RAML.
{
use(new ApiTool()
.disableTryIt()
);
}
Disable UI for Swagger or RAML.
{
use(new ApiTool()
.disableUI()
);
}
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.
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.
| Modifier and Type | Class and Description |
|---|---|
static class |
ApiTool.Options
Export options.
|
| Constructor and Description |
|---|
ApiTool()
Creates a new ApiTool.
|
ApiTool(Path basedir)
Creates a new instance of ApiTool.
|
| Modifier and Type | Method and Description |
|---|---|
com.typesafe.config.Config |
config() |
void |
configure(Env env, com.typesafe.config.Config conf, com.google.inject.Binder binder)
Configure and produces bindings for the underlying application.
|
ApiTool |
disableTryIt()
Turn off live-testing (try button) for Swagger and Raml.
|
ApiTool |
disableUI()
Turn off UI for Swagger and Raml.
|
ApiTool |
filter(Predicate<RouteMethod> predicate)
Select which route is going to be exported to Swagger/RAML.
|
ApiTool |
modify(Predicate<RouteMethod> matcher, Consumer<RouteMethod> customizer)
Modify one or more route method who matches the filter.
|
ApiTool |
raml()
Mount RAML using at /raml.
|
ApiTool |
raml(ApiTool.Options options)
Mount RAML using the given options.
|
ApiTool |
raml(ApiTool.Options options, Consumer<Raml> raml)
Mount RAML using the given options.
|
ApiTool |
raml(String path)
Mount RAML at the given path.
|
ApiTool |
raml(String path, Consumer<Raml> raml)
Mount RAML at the given path and customize RAML objects.
|
ApiTool |
redoc()
Mount ReDoc at /redoc
|
ApiTool |
redoc(String path)
Mount ReDoc at /redoc
|
ApiTool |
swagger()
Mount Swagger at /swagger
|
ApiTool |
swagger(ApiTool.Options options)
Mount Swagger using the given options.
|
ApiTool |
swagger(ApiTool.Options options, Consumer<io.swagger.models.Swagger> swagger)
Mount Swagger using the given options.
|
ApiTool |
swagger(Consumer<io.swagger.models.Swagger> swagger)
Mount Swagger at /swagger and set a customizer.
|
ApiTool |
swagger(String path)
Mount Swagger at the given path.
|
ApiTool |
swagger(String path, Consumer<io.swagger.models.Swagger> swagger)
Mount Swagger at the given path and customize Swagger objects.
|
public ApiTool(Path basedir)
ApiTool.
basedir - Base directory to lookup for javadoc.
public ApiTool()
ApiTool.
public void configure(Env env, com.typesafe.config.Config conf, com.google.inject.Binder binder) throws Exception
Jooby.Module
application env and/or the current application properties available from Config.
configure in interface Jooby.Module
env - The current application's env. Not null.
conf - The current config object. Not null.
binder - A guice binder. Not null.
Exception
public com.typesafe.config.Config config()
config in interface Jooby.Module
public ApiTool filter(Predicate<RouteMethod> predicate)
predicate - True, if route is exported.
public ApiTool disableUI()
public ApiTool disableTryIt()
public ApiTool swagger()
/swagger
public ApiTool redoc()
/redoc
public ApiTool redoc(String path)
/redoc
path - Redoc path.
public ApiTool swagger(String path)
path - Path to mount swagger.
public ApiTool swagger(Consumer<io.swagger.models.Swagger> swagger)
/swagger and set a customizer.
swagger - Swagger customizer.
public ApiTool swagger(String path, Consumer<io.swagger.models.Swagger> swagger)
path - Path to mount swagger.
swagger - Customizer.
public ApiTool swagger(ApiTool.Options options)
options - Swagger options.
public ApiTool swagger(ApiTool.Options options, Consumer<io.swagger.models.Swagger> swagger)
options - Swagger options.
swagger - Customizer.
public ApiTool raml()
/raml.
public ApiTool raml(String path)
path - Path to mount raml.
public ApiTool raml(String path, Consumer<Raml> raml)
path - Path to mount raml.
raml - RAML customizer.
public ApiTool raml(ApiTool.Options options)
options - RAML options.
public ApiTool raml(ApiTool.Options options, Consumer<Raml> raml)
options - RAML options.
raml - RAML customizer.
public ApiTool modify(Predicate<RouteMethod> matcher, Consumer<RouteMethod> customizer)
matcher - Route matcher.
customizer - Customizer.
Copyright © 2019. All rights reserved.