Library for OpenAPI 3 with spring-boot

View project on GitHub F.A.Q Migration from springfox

Migrating from SpringFox

  • Remove springfox and swagger 2 dependencies. Add springdoc-openapi-ui dependency instead.
  • Replace swagger 2 annotations with swagger 3 annotations (it is already included with springdoc-openapi-ui dependency). Package for swagger 3 annotations is io.swagger.v3.oas.annotations.

    • @ApiParam -> @Parameter
    • @ApiOperation -> @Operation
    • @Api -> @Tag
    • @ApiImplicitParams -> @Parameters
    • @ApiImplicitParam -> @Parameter
    • @ApiIgnore -> @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
    • @ApiModel -> @Schema
    • @ApiModelProperty -> @Schema
  • This step is optional: Only if you have multiple Docket beans replace them with GroupedOpenApi beans.


        public Docket publicApi() {
            return new Docket(DocumentationType.SWAGGER_2)
        public Docket adminApi() {
            return new Docket(DocumentationType.SWAGGER_2)


        public GroupedOpenApi publicApi() {
            return GroupedOpenApi.builder()
        public GroupedOpenApi adminApi() {
            return GroupedOpenApi.builder()

    If you have only one Docket – remove it and instead add properties to your application.properties:

    springdoc.packagesToScan=package1, package2
    springdoc.pathsToMatch=/v1, /api/balance/**
  • Add bean of OpenAPI type. See example:
        public OpenAPI springShopOpenAPI() {
            return new OpenAPI()
                    .info(new Info().title("SpringShop API")
                    .description("Spring shop sample application")
                    .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                    .externalDocs(new ExternalDocumentation()
                    .description("SpringShop Wiki Documentation")
  • If the swagger-ui is served behind a proxy:
  • To customise the Swagger UI
  • To hide an operation or a controller from documentation