Contributing to the central OpenAPI definition from a module is very easy.
Just override/implement mountRouteHandlers in your module's gateway hook. The Route class we provide has an OpenAPI builder attached to it you can use to build up a response.
@Override
public void mountRouteHandlers(RouteGroup routes) {
routes.newRoute("/api/v1/session/:sessionId/pages")
.type(RouteGroup.TYPE_JSON)
.method(HttpMethod.GET)
.requirePermission(PermissionType.READ)
.itemListHandler(this::getSessionPages)
.itemSerializer(gson)
.itemSchema(SchemaUtil.fromType(PerspectivePageInfo.class))
.openApi(api -> api
.tag(SESSION_TAG)
.summary("Perspective Pages")
.description("Retrieves a list of all pages in a session.")
.pathParameter("sessionId", "ID of the session", JsonType.STRING, null)
.response(SC_NOT_FOUND, "The session ID does not exist"))
.mount();
By default, routes added in this way will be exposed under $host/data/$yourModuleId/$whateverRouteMountingPath - so in the example above, you would
POST http://localhost:8088/data/myModuleId/someName
You can override getMountPathAlias on your gateway hook to replace yourModuleId with some shorter alias for friendlier URLs - you're just in charge of avoiding collisions then.
There isn't any directly supported way to add custom URLs within an existing prefix, such as resources, but you can add them to /api/v1/, just like a bunch of our first party modules do.
You should 'qualify' your additional methods as belonging to your module so it's clear to end users:
routes.addOpenApiGroup("Perspective", SESSION_TAG);
routes.addOpenApiGroup("Perspective", CONFIG_THEMES_TAG);
And as for:
You don't have to, if you use our route mounting system.
.requirePermission(PermissionType.READ) (or PermissionType.ACCESS/WRITE)
will automatically require the appropriate gateway access permission. If you really want to have a distinct meaning of permissions, it's certainly possible, but you're going to have an easier time if you stick to what we provide for you automatically.