Create Open API documentation for a Spring boot app.

Getting started with springdoc-openapi:

To add Open API documentation(previously swagger) for an api all we need to do is to add the below springdoc-openapi-ui maven dependency.

 <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.6.9</version>
   </dependency>

By default the documentation will be available at http://localhost:8080/context-path/swagger-ui.html.

Additional Options

For a custom path use springdoc.swagger-ui.path=/my-swagger-ui.html
To disable swagger-ui use springdoc.swagger-ui.enabled=false
To disable /v3/api-docs endpoint use springdoc.api-docs.enabled=false
To exclude a rest controller from documentation use @Hidden annotation.
To display the endpoints of rest controllers available only in some specific packages use springdoc.packagesToScan=com.jsession4d, com.package2
To specify paths to match for documentation use springdoc.pathsToMatch=/v1, /api/user/**

Customizing Swagger ui html.

To edit the contents of swagger-ui.html we create Docket bean in spring fox. While migrating from springfox to Springdoc remove Docket bean and create an OpenAPI bean.

@Bean
public OpenAPI userServiceOpenAPI() {
   return new OpenAPI()
         .info(new Info().title("Jsession4D User API")
               .description("Sample API to maintain Users")
               .version("v0.0.1")
               .license(new License().name("Apache 2.0").url("https://jsession4d.com/")))
         .externalDocs(new ExternalDocumentation()
               .description("Spring demos")
               .url("https://jsession4d.com/spring/"));
}

NOTE:

As of this writing on June 2022, Springfox swagger project was not actively developed. The last commit in the git hub was on Oct 13 2020. Using spring fox swagger libraries for a spring boot project is giving errors like “Failed to start bean ‘documentationPluginsBootstrapper” with the the latest Spring boot versions. So the best choice for creating swagger documentation for a Spring boot app is to use springdoc-openapi libraries.

Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException: Cannot invoke "org.springframework.web.servlet.mvc.condition.PatternsRequestCondition.getPatterns()" because "this.condition" is null

Even if we set the below path match property to fix the above error, adding spring boot actuator again breaks the build with the same error.

spring:
  mvc:
    pathmatch:
      matching-strategy: ant-path-matcher

Generate Code from swagger or Open API doc using plugin.

To generate code from an open api documentation use openapi-generator-maven-plugin. To generate code from swagger v2 or v1 doc use swagger-codegen-maven-plugin.

Note: openapi-generator-maven-plugin also supports code generation from swagger v2 besides open api.

How to identify a open api or swagger v2 or v1 doc ?

Open api docs start with the tag openapi (ex: "openapi" : "3.0.1"). Swagger docs start with the tag swagger (ex: "swagger" : "2.0")

openapi-generator-maven-plugin example.

<plugin>
   <groupId>org.openapitools</groupId>
   <artifactId>openapi-generator-maven-plugin</artifactId>
   <version>5.4.0</version>
   <executions>
      <execution>
         <goals>
            <goal>generate</goal>
         </goals>
         <configuration>             <inputSpec>${project.basedir}/src/main/resources/OpenApi.json/yml</inputSpec>
            <generatorName>spring</generatorName>
            <configOptions>
               <interfaceOnly>true</interfaceOnly>
               <library>spring-boot</library>
               <serializableModel>true</serializableModel>
               <apiPackage>com.jsession4d.user.api</apiPackage>
               <modelPackage>com.jsession4d.user.model</modelPackage>
            </configOptions>
         </configuration>
      </execution>
   </executions>
</plugin>

Note:

If you see errors like “springfox.documentation.annotations does not exist” or “io.swagger.annotations does not exist” use at least version 5.4.0 to generate swagger v3 annotations “io.swagger.v3.oas.annotations“.
If you see error like “package org.openapitools.jackson.nullable does not exist” add the following dependency.

<dependency>
   <groupId>org.openapitools</groupId>
   <artifactId>jackson-databind-nullable</artifactId>
   <version>0.2.2</version>
</dependency>

Swagger-codegen-maven-plugin example

<plugin>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.4.27</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>                <inputSpec>${project.basedir}/src/main/resources/UserSwagger.json</inputSpec>
                <language>spring</language>
                <configOptions>
                    <interfaceOnly>true</interfaceOnly>
                    <library>spring-boot</library>
                    <serializableModel>true</serializableModel>
                    <java8>true</java8>
                    <apiPackage>com.jsession4d.user.api</apiPackage>
                    <modelPackage>com.jsession4d.user.model</modelPackage>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>