Generating OpenAPI from Code
Java Spring Boot

OpenAPI and Java Spring Boot with Optic

To begin using Optic with your API you first need an OpenAPI file describing your API. This YAML or JSON file can be written by hand or generated from your code. This document describes the recommended process for generating a new OpenAPI file for a Java Spring Boot projects.

We recommend using the springdoc-openapi (opens in a new tab) package to generate an OpenAPI 3 specification file from your code.

To follow along, you'll need the following tools installed:

Getting started

  1. Start by cloning Spring Boot's getting start repo, git clone

  2. Enter the "complete" directory, cd gs-spring-boot/complete.

  3. In the build.gradle file, insert the following line into the dependencies section to add the springdoc-openapi package to the project,

    implementation group: 'org.springdoc', name: 'springdoc-openapi-starter-webmvc-ui', version: '2.1.0'

    You should wind up with a diff similar to,

    $ git diff build.gradle
    diff --git a/complete/build.gradle b/complete/build.gradle
    index 0a3df9e..d6ef80c 100644
    --- a/complete/build.gradle
    +++ b/complete/build.gradle
    @@ -13,6 +13,7 @@ repositories {
     dependencies {
    +       implementation group: 'org.springdoc', name: 'springdoc-openapi-starter-webmvc-ui', version: '2.1.0'
            // tag::actuator[]
            implementation 'org.springframework.boot:spring-boot-starter-actuator'
            // end::actuator[]
  4. Start the app, ./gradlew bootRun.

  5. Once started, the app will be serving an OpenAPI 3 spec at http://localhost:8080/v3/api-docs.yaml (YAML), or http://localhost:8080/v3/api-docs (JSON). Since Optic works by comparing OpenAPI specs across branches, you should write the file to disk (and check it into source control if this weren't a sample project): curl http://localhost:8080/v3/api-docs.yaml > openapi.yml.

Additional package configuration details are available on SpringDocs's site (opens in a new tab).


In your own project, you may want to automate the final step of updating your openapi.yml file with a build task, Git hook, or similar to keep the file up to date.

What's next

Automate your OpenAPI generation and test your API specifications by setting up Optic in CI.