Implementing OpenAPI / Swagger documentation for Bienenvolk Grails-based modules (using SpringBootMVC plugins)

Updates to build.gradle

The following packages should be added to the module's build.gradle:

implementation 'org.springdoc:springdoc-openapi-ui:1.6.5'

Updates to application.yml

Additionally a springdoc field should be added to the module's application.yml. Here is an example for mod-agreements. The “packages-to-scan” would need to be updated to be correct for the module being worked on:

springdoc:
  api-docs:
    path: /api
  packages-to-scan: org.olf.agreements.controllers
  swagger-ui:
    path: /docsui
      tryItOutEnabled: true
      operationsSorter: method
      tagsSorter: alpha
      filter: true

New configuration class

A configuration class for OpenAPI should be added within the config folder. This will be used to setup the top level fields of the OpenAPI json - including the Info object and the server objects. Note: this should be within the src/main/java file directory within the module.

An example is shown below:

package org.olf.agreements.config;
import java.util.List;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.servers.Server;

@Configuration
public class OpenAPIConfig {

  @Value("${someurl}")
  private String devUrl;
    
  @Value("${prod-url}")
  private String prodUrl;
    
  @Bean
  public OpenAPI myOpenAPI() {
    Server devServer = new Server();
    devServer.setUrl(devUrl);
    devServer.setDescription("Server URL in Development environment");
    
    Server prodServer = new Server();
    prodServer.setUrl(prodUrl);
    prodServer.setDescription("Server URL in Production environment");
    
    Contact contact = new Contact();
    contact.setEmail("some-contact-address@gmail.com");
    contact.setName("some-contact-name");
    contact.setUrl("https://some-contact-url.com");
    
    License mitLicense = new License().name("MIT License").url("https://some-license-url/");
    
    Info info = new Info()
        .title("Tutorial Management API")
        .version("1.0")
        .contact(contact)
        .description("This API exposes endpoints to manage tutorials.").termsOfService("https://www.some-terms-url.com/terms")
        .license(mitLicense);
    
    return new OpenAPI().info(info).servers(List.of(devServer, prodServer));
  }
}

Changes to module controller classes

Existing controller classes will need to be refactored into java removing any grails/groovy specific methods that are currently used. It may also be necessary to expose hidden methods which are currently created automatically by Grails.

Tag annotation is used to create the Tag Object in the resulting OpenAPI specification
RestController annotations are required at the top level of each controller class defining the name and description of that controller

An example set of annotations for a class is as follows:

@Tag(name = "Tutorial", description = "Tutorial management APIs")
@RestController
public class TestController {

Each method in controller will need an expected response body implemented directly into the controller. For example:

Below is an example of how the methods within said controller should be annotated, this includes the following annotations:

Operation annotation is used to define the OpenAPI Operation object which describes a single API operation on a path.
ApiResponses and ApiResponse annotations are used to define the OpenAPI Responses and Response objects respectively. These define the responses which can be returned from the method, including the HTTP response code and content, note that with a 200 response we also have the previously defined DummyResponse as the content for that ApiResponse.
Finally for this example we use the GetMapping annotation to define the endpoint for this method

A full example of this controller implementation is below, along with required package: