SpringBot Developer Documentation

Once a SpringBot application has been built and is running, some developer documentation becomes available which can assist developers in making custom changes.

Server-side

API Documentation

SpringBot provides two APIs that can be utilised:

• REST API
• GraphQL API

API documentation is available once the How do I run my app? when run using either the test or dev profiles. For details on the different profiles please see SpringBot application profiles and configuration.

More details on running SpringBot can be found in Running SpringBot.

REST API - Swagger

Swagger documentation is provided by the running target application, showing a full spec for the REST API that is written by the bots. This documentation is live, and automatically updates when new controller endpoints are added; be they custom or bot written. This bot written documentation also includes descriptions and details around the purpose of each endpoint.

As the Swagger UI is hosted by the running application, it can be interacted with by adding a valid authorisation token (found by inspecting the response to logging into the application).

The Swagger UI can be accessed at /swagger-ui.html of your running application, a JSON version can also be found at /v3/api-docs.

GraphQL - Voyager

The second API that is available in the target application is GraphQL. For GraphQL we have two main interfaces where you can gain access to introspection and view how the API is structured.

The first is Voyager.

Please see the GraphQL Voyager offical demo for an example of how this works.

This interface allows us to explore our GraphQL API as an interactive graph.

This is available in the running application at /voyager.

GraphQL - GraphiQL/Altair

The second interface that is made available for exploring the GraphQL API is GraphiQL (see here for a live demo). This interface allows for introspective similar to Voyager, but the key difference being that it also explores the API by running queries against it. GraphiQL adds auto-complete to make this easier.

GraphiQL can be found at /graphiql

An Altair is also embedded in the running target application to allow for a slightly different experience to GraphiQL when exploring the API. In the same way that GraphiQL does, Altair allows you to query the API with auto-complete. Altair does offer some more advanced features such as the ability to set headers.

Altair can be found at /altair.

Javadoc

Javadoc can be generated using the command ./gradlew javadoc from inside the serverside directory. This will create your server-side technical documentation that you can access at serverside/build/docs/javadoc.

Spring Actuator

Spring Boot actuator is available within the application with anonymous access available for the test profiles.

This can be used to provide huge amounts of information about the state of the running application. For details, see Endpoints.

Client-side

Client-side documentation can be generated using the provided Compodoc documentation tool.

For more details please see Angular Docs with CompoDoc.