Documenting RESTful Services with Rebel Plus and Swagger

1. Overview

It is difficult to emphasize enough the importance of documenting your RESTful services - and your work in general.

Documenting RESTful services using Swagger is an excellent choice, especially if you use the Spring framework. And if you use the Rebel Plus, this important, yet easy task gets even easier.

This article will show you how to use the Rebel Plus to connect Swagger documentation with your UML model and how to configure Swagger in your Spring application.

We will use the example previously introduced in Developing a Spring Boot RESTful Service with Rebel Plus.

Let us see the power and simplicity of model-driven development!

2. Maven Dependencies

To enable Swagger in our project, we will add two Maven dependencies to our project:

By its definition, "the Springfox suite of Java libraries are all about automating the generation of the machine and human-readable specifications for JSON APIs written using the Spring family of projects. Springfox works by examining an application, once, at runtime to infer API semantics based on Spring configurations, class structure, and various compile-time java annotations."

On the other hand, the Swagger UI visualizes the definition of services provided by the Springfox and allows you to explore services and interact with them.

3. Swagger Configuration

To configure the behavior and scope of Springfox, we need to define a Spring bean known as docket in Springfox terminology:

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    @Bean
    public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.archetype"))
        .paths(PathSelectors.ant("/*"))
        .build()
        .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfo(
        "Eatalian REST API",
        "Description: What is life a shadow of a fleeting dream?",
        "1.0.0",
        "Terms of service",
        new Contact("ArchRebel",
        "https://www.archetypesoftware.com",
        "[email protected]"),
        "License of API", "API license URL", Collections.emptyList());
    }
}

According to the official Springfox documentation, a docket stands for "a summary or other brief statement of the contents of a document; an abstract."

However, in this case, we use our docket bean to instruct the Springfox which packages to scan in order to build the Swagger documentation, what information to provide to Swagger GUI, etc.

For more information about customizing Springfox, you can always refer to the Springfox reference documentation, as well as Baeldung Guide to Setting up Swagger with Spring REST API.

4. Rebel Plus: Documentation Profile

The description of the data model is an aspect of Swagger documentation that you can easily customize, using annotations such as @Api, @ApiModel or @ApiModelProperty, as shown in the picture below.

To establish a connection between your UML model and Swagger documentation, the Rebel Plus introduces the Documentation profile.

By using the Rebel Documentation profile, you can instruct Rebel to generate documentation from your UML model using Swagger annotations, instead of the (default) Javadoc format.

5. Rebel Plus Documentation Profile: How it works?

When you select a package or a class, you can customize the Rebel Plus Documentation properties by using one of the predefined values:

• inherit from parent,
• javadoc,
• swagger,
• none.

The last three options: javadoc, swagger and none are used to customize the mapping of model documentation to one of the selected output formats. Whatever you select - will be the output format for that particular model element.

The first option, inherit from parent, the default value for documentation format, gives you the possibility to easily customize the export documentation for multiple model elements at once.

For example, if you set the documentation format for the domain package to swagger, documentation of all domain sub-packages will be generated using Swagger annotations, while the rest of the project will use its own documentation settings and will be either exported as Javadoc or Swagger or will not be exported at all.

Typically, you will set documentation format to swagger only for those packages that contain resources used by your Spring Controllers. If you place all of them under the single package, it is enough to set documentation format to swagger only for that single package, while all its children will inherit its documentation format by default.

6. Benefits of Using Swagger

Using Swagger to document your services offers numerous advantages:

• Documentation becomes an integral part of your project,
• The Springfox recognizes Spring Controllers and their mappings; as you develop your application, the documentation automatically grows.
• The Swagger UI exposes your API documentation using the Web GUI.
• The Swagger UI offers the possibility to invoke services, experience the behavior of your application and test it.
• You can export your Swagger definition in YAML or JSON format and use it as an input for numerous tools that give you additional possibilities:
  • Generate client libraries in different languages,
  • Generate a running mocks
  • Present and discuss your APIs using Swagger Editor, etc.

7. Putting It All Together

In this article, we have explained how to use Rebel Plus to automatically export documentation from your UML model into the Swagger documentation provided by the Springfox and Swagger UI.

In this way, not only you can automate the development of your RESTful services, but it can also additionally enhance the quality of your documentation and reduce the amount of effort needed to keep it up to date.

We hope that you have enjoyed the journey! As a small reward for your perseverance, you can use coupon code APPRECIATION2019 to claim a 20% discount off the annual subscription for both individual and business licenses, until the end of 2019!

To provide out-of-the-box Swagger documentation for your RESTful services, upgrade to Rebel Plus.