Quickstart: Spring Boot

livedoc-springboot is almost identical to the Spring MVC flavour, but you have even less work to do!

Like livedoc-springmvc, it knows Spring annotations and is able to generate a documentation without further configuration. Combined with Javadoc processing, it allows you to generate a complete documentation without a single Livedoc annotation.

Add a dependency on livedoc-springboot

compile 'org.hildan.livedoc:livedoc-springboot:5.2.0'

<dependency>
    <groupId>org.hildan.livedoc</groupId>
    <artifactId>livedoc-springboot</artifactId>
    <version>5.2.0</version>
</dependency>

<dependency org='org.hildan.livedoc' name='livedoc-springboot' rev='5.2.0'>
    <artifact name='livedoc-springboot' ext='pom' />
</dependency>

If you want to generate part of your documentation (descriptions) from your Javadoc, you also need to add the Livedoc Javadoc processor.

Add the required configuration in application.properties

If not already present, you may create application.properties in src/main/resources (at the root, without package), and add the following content:

livedoc.packages=com.mycompany.controller,com.mycompany.model,org.example.external.model

That’s right, the package list is the only required configuration for livedoc. If you want a bit more control, you may configure other properties:

livedoc.name=My API
livedoc.version=1.0
livedoc.packages=com.mycompany.controller,com.mycompany.model,org.example.external.model
livedoc.baseUrl=http://localhost:8080/api
livedoc.playgroundEnabled=true
livedoc.displayMethodAs=URI

Here is what each of these properties means:

Name Default Description
name null a descriptive name for your API. Used in the default home page.
version null the current version of your API, if relevant
packages required a list of packages that Livedoc should scan for controllers. Also acts as a whitelist for documented types: types outside these packages won’t be documented.
baseUrl current server+context the base URL that client should target to reach your API
playgroundEnabled true allows to send requests directly from Livedoc UI, in order to try the API
displayMethodAs URI displays the operations by their endpoint path (URI), their corresponding handler method name (METHOD) or their short description (SUMMARY)

Using generated build info

If you’re using the Gradle Spring Boot plugin, you can make your app’s name and version available by adding the following lines to your build.gradle:

springBoot {
    buildInfo()
}

You can read more information about this in the official documentation of the plugin.

If the build info is available, Livedoc will fall back to this when you don’t provide the name or version in your application.properties.

Enable JSON documentation on your configuration class

@SpringBootApplication
@EnableJSONDoc
public class MyWebapp {
    
    public static void main(String[] args) {
        SpringApplication.run(MyWebapp.class, args);
    }
}

This will automatically register a controller that serves the documentation as JSON at the /jsondoc endpoint.

Access the documentation

By navigating to the /jsondoc endpoint on your server, you may get the JSON description of your documentation.

More interesting, you may also use the provided UI with very few steps.

Note on Livedoc’s JSON serialization

Sometimes, you’d like to configure a custom Jackson ObjectMapper for your API, which is a legitimate need. Such a custom mapper could affect Livedoc’s JSON output, which in turn could break the Livedoc UI.

This is why @EnableJSONDoc also registers a LivedocMessageConverter, which handles Livedoc’s custom media type application/livedoc+json returned by /jsondoc, using an independent ObjectMapper.

This won’t affect your own API, but it may be surprising that the JSON produced by /jsondoc does not follow your configuration, hence this short note.