Weblux swagger pomocí springfox

Swagger je nástroj (knihovna), který umožňuje dokumentovat REST endpointy vaší aplikace. Dobré je to například pro vývoj, kdy konzument (např. vývojář frontendu) ví, jaké jsou aktuálně k dispozici endpointy, jaké mají vstupy a jaké objekty vrací. Jak zprovoznit swagger v projektu, který používá WebFlux a Spring Boot ukáži v tomto příspěvku.

Pokud máte projekt a používáte pro restové služby framework WebFlux a Spring Boot, je zprovoznění Swaggeru jednoduché. Stačí přidat následující závislosti (používám Gradle a Kotlin):

implementation("io.springfox:springfox-swagger2:3.0.0-SNAPSHOT")
implementation("io.springfox:springfox-swagger-ui:3.0.0-SNAPSHOT")
implementation("io.springfox:springfox-spring-webflux:3.0.0-SNAPSHOT")

a vytvořit konfigurační třídu pro Swagger:

@Configuration
@EnableSwagger2WebFlux
class SwaggerConfiguration {

    @Bean
    fun api(): Docket {
        return Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo())
                .enableUrlTemplating(true)
                .enable(true)
    }

    private fun apiInfo(): ApiInfo {
        return ApiInfoBuilder()
                .title("Webflux springfox swagger application")
                .description("Project to show usage of swagger in webflux rest application")
                .version("1.0.0")
                .contact(Contact("vitfo", "www.vitfo.cz", "noemail"))
                .license("Apache License, Version 2.0")
                .licenseUrl("https://opensource.org/licenses/Apache-2.0")
                .build()
    }
}

To je pro vygenerování té nejzákladnější funkcionality vše. Pokud nyní spustíte aplikaci, tak na stránce /swagger-ui.html (http://localhost:8080/swagger-ui.html) budete mít vygenerovanou dokumentaci. Například pro endpoint /message, který vyžaduje parametr identifier

@GetMapping("/message")
fun getMessageParam(@RequestParam identifier: String): Mono<ResponseEntity<Message>> { ... }

to bude vypadat následovně:

Je to alespoň něco, ale určitě by to mohlo být lepší. Pro to slouží anotace io.swagger.annotations.

@ApiOperation (umožňuje přidat popis endpointu a specifikovat návratový typ)

@ApiOperation("Save message", response = String::class)
@PostMapping("/message")
fun saveMessage(@RequestBody messageToSave: Message): Mono<ResponseEntity<String>> { ... }

@ApiParam (umožňuje přidat popis a další informace k parametru)

@ApiOperation("Get message by its identifier", response = MessageV2::class)
@GetMapping("/message_v2")
fun getMessageParamDetailedInformation(
        @ApiParam(value = "Identifier of the message", name = "identifier", allowableValues = "m1 to m1000", example = "m100", allowEmptyValue = false)
        @RequestParam identifier: String): Mono<ResponseEntity<MessageV2>> { ... }

Díky ApiInfo, které jsme definovali v konfigurační třídě, se zobrazí tyto informace:

Celou aplikaci naleznete na githubu: github.com/vitfo/webflux-springfox-swagger