How to Swagger

This page refers to las2peer versions older than 0.6.1!

Serving Swagger for a las2peer Service

Once you have created your restful las2peer service, you should provide good documentation for external developers. las2peer uses Swagger for this purpose. With a couple of additional annotations to your service, las2peer (in particular the las2peer Web Connector) auto-generates Swagger documents and hosts them along with your service. This tutorial provides instructions on how to achieve this in two steps.

1. Annotate your service

Take a look at the available Swagger annotations on this documentation to make your las2peer service swagger-ready by adding the required annotations to your service.

An example for an Swagger annotated service is the TemplateService itself.

2. Get Swagger API Listing

The Swagger API listing's endpoint is Swagger compliant under http(s)://ROOT_URL/serviceName/[exactServiceVersion/]swagger.json and serves Swagger documentation for the service having the serviceName as root URI.

3. Integrate Swagger with OpenID Connect

The WebConnector sets up the default OIDC provider (hardcoded to https://api.learning-layers.eu/o/oauth2) as security definition and tells Swagger to use Authentication for each method. To use OpenID Connect in Swagger-UI, you need to register a client at the default provider (see https://github.com/learning-layers/openid-connect-button for instructions). Then download Swagger UI, open dist/index.html, find these lines in the code and fill in clientId, clientSecret and appName:

if(typeof initOAuth == "function") {
    initOAuth({
        clientId: "your-client-id",
        clientSecret: "your-client-secret-if-required",
        realm: "your-realms",
        appName: "your-app-name",
        scopeSeparator: ",",
        additionalQueryStringParams: {}
    });
}

Done!