Swagger 2 using Springfox (Spring Boot)

Introduction

Swagger allows you to describe the structure of your APIs so that machines can read them.

As of 2019-dec, Springfox is abandoned (not compatible with Spring Boot 2.2).

An alternative is springdoc-openapi [https://stackoverflow.com/questions/58626347/springfox-swagger-not-working-in-spring-boot-2-2-0].

Reference for springdoc-openapi (OpenAPI 3) [https://github.com/springdoc/springdoc-openapi]

Warning: 'openapi-generator-maven-plugin' as of version 4.2.2 generated sources with Springfox annotation. As of version 5.0.0 the project has moved to springdoc.

References

• Setting Up Swagger 2 with a Spring REST API

http://www.baeldung.com/swagger-2-documentation-for-spring-rest-api

Configuration

Restrict swagger generation to a specific package and paths:

package edu.cou.doc;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**

 * Swagger 2 config.<br>

 */

@Configuration

@EnableSwagger2

public class SwaggerConfig {

 @Bean

 public Docket api() {

  return new Docket(DocumentationType.SWAGGER_2).select()

    .apis(RequestHandlerSelectors.basePackage("edu.cou.doc.rest"))

    // Exclude paths starting with '/tech' or '/test*'

    .paths(PathSelectors.regex("(?!/tech).+")).paths(PathSelectors.regex("(?!/test).+"))

    .build();

 }

}

Enable Authorization Bearer token

Add to SwaggerConfig the securitySchemes, eg:

import java.util.ArrayList;

import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import com.google.common.base.Predicates;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiKey;

import springfox.documentation.service.SecurityScheme;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration

@ConditionalOnExpression("'${env}' != 'pre' or '${env}' != 'pro'")

@EnableSwagger2

public class SwaggerConfig {

  @Bean

  Docket api() {

    return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.any())

        .paths(Predicates.not(PathSelectors.regex("/login.*|/error.*"))).build()//

        .securitySchemes(securitySchemes());

  }

  private static ArrayList<? extends SecurityScheme> securitySchemes() {

    ArrayList<ApiKey> ret = new ArrayList<>();

    ret.add(new ApiKey("Bearer", "Authorization", "header"));

    return ret;

  }

}

And to the controller operation the @ApiOperation annotation with the authorizations attribute:

  @ApiOperation(value = "Get equipments by id", authorizations = @Authorization(value = "Bearer"))

  @GetMapping(value = "/{id}", produces = { MediaType.APPLICATION_JSON_VALUE })