Swagger API documentation

Description

Imagine that you are entering to a new project and would like to check how does the outside world communicate with your Spring application. How would you do it? How would you test your application? You can search your code for @Controller annotated methods but we don't like to do lame stuff - we are too cool to do that.

That's why we use Swagger. And you should too - check out their live demo. It's documenting your API automatically but you can provide more annotations to describe your API even more beautifully.

Backend API documentation

Swagger consists of two separate parts - documenting API (backend) and presentation of the API (swagger-ui). The configuration presented below shows you how to add the backend API documentation.

Example of usage

Below you can find an example of some of Swagger's annotations in action.

package com.ofg.infrastructure.healthcheck

import com.wordnik.swagger.annotations.Api
import com.wordnik.swagger.annotations.ApiOperation
import groovy.transform.CompileStatic
import groovy.transform.PackageScope
import org.springframework.http.MediaType
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RequestMethod
import org.springframework.web.bind.annotation.RestController

/**
 * {@link RestController} that responds with OK when server is alive
 */
@RestController
@CompileStatic
@PackageScope
@Api(value = "ping", description = "PING API")
class PingController {

    @RequestMapping(value = "/ping", method = RequestMethod.GET, produces = MediaType.TEXT_PLAIN_VALUE)
    @ApiOperation(value = "Ping server", notes = "Returns OK if server is alive")
    String ping() {
        return "OK"
    }
}

Module configuration

If you want to use only this module just add a dependency:

repositories {
    jcenter()
}

dependencies {
    compile 'com.ofg:micro-infra-spring-swagger:0.6.0'
}

and enable this via annotation:

@Configuration
@EnableMicroserviceDocumentation
class MyWebAppConfiguration {
}