tobiaskrauss/restdocs-spec

A maven plugin for generating Open API and Postman Collection specifications using Spring Restdocs.

Restdocs Spec Generation Support

Usage

First head over to the ePages-de/restdocs-api-spec project and follow the instructions for setting up the Spring REST Docs extension. That extension will produce resource.json files for each of your documented resources. You'll also notice that project provides a gradle plugin that can be used to read all the resource.json files and turn them into an OpenAPI spec file. That is exactly what this project does as well, only in the form of a maven plugin instead.

Here is a typical pom.xml configuration:

  <plugin>
    <groupId>io.github.berkleytechnologyservices</groupId>
    <artifactId>restdocs-spec-maven-plugin</artifactId>
    <version>${restdocs-spec.version}</version>
    <executions>
      <execution>
        <goals>
          <goal>generate</goal>
        </goals>
      </execution>
    </executions>
  </plugin>

That will read your resource.json snippet files found under the ${project.build.directory}/generated-snippets directory and produce an OpenAPI 2.0 YAML file at ${project.build.directory}/restdocs-spec/openapi-2.0.yml.

If you would prefer that the OpenAPI 2.0 document is in JSON format you can specify it like this:

  <plugin>
    <groupId>io.github.berkleytechnologyservices</groupId>
    <artifactId>restdocs-spec-maven-plugin</artifactId>
    <version>${restdocs-spec.version}</version>
    <executions>
      <execution>
        <goals>
          <goal>generate</goal>
        </goals>
        <configuration>
          <format>JSON</format>
        </configuration>
      </execution>
    </executions>
  </plugin>

You can also generate OpenAPI 3.0 or Postman Collection specification. For instance, this would generate OpenAPI 3.0:

  <plugin>
    <groupId>io.github.berkleytechnologyservices</groupId>
    <artifactId>restdocs-spec-maven-plugin</artifactId>
    <version>${restdocs-spec.version}</version>
    <executions>
      <execution>
        <goals>
          <goal>generate</goal>
        </goals>
        <configuration>
          <specification>OPENAPI_V3</specification><!-- switch this to POSTMAN_COLLECTION for Postman Collection specs -->
        </configuration>
      </execution>
    </executions>
  </plugin>

Finally, you can also generate multiple formats at once using the more verbose syntax:

  <plugin>
    <groupId>io.github.berkleytechnologyservices</groupId>
    <artifactId>restdocs-spec-maven-plugin</artifactId>
    <version>${restdocs-spec.version}</version>
    <executions>
      <execution>
        <goals>
          <goal>generate</goal>
        </goals>
        <configuration>
          <specifications>
            <specification>
              <type>OPENAPI_V2</type>
            </specification>
            <specification>
              <type>OPENAPI_V3</type>
              <format>JSON</format>
            </specification>
            <specification>
              <type>POSTMAN_COLLECTION</type>
              <filename>my-api-collection</filename>
            </specification>
          </specifications>
        </configuration>
      </execution>
    </executions>
  </plugin>

There are several other aspects you can optionally configure. Here is the full set of options with their default values:

  <plugin>
    <groupId>io.github.berkleytechnologyservices</groupId>
    <artifactId>restdocs-spec-maven-plugin</artifactId>
    <version>${restdocs-spec.version}</version>
    <executions>
      <execution>
        <goals>
          <goal>generate</goal>
        </goals>
        <configuration>
          <name>${project.artifactId}</name>
          <version>${project.version}</version>
          <host>localhost</host>
          <basePath></basePath>
          <schemes>
            <scheme>http</scheme>
          </schemes>
          <snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
          <specification>OPENAPI_V2</specification>
          <outputDirectory>${project.build.directory}/restdocs-spec</outputDirectory>
          <skip>false</skip>
          <format>YAML</format>
          <filename>openapi-2.0</filename>
          <separatePublicApi>false</separatePublicApi>
          <tags />
          <oauth2 />
        </configuration>
      </execution>
    </executions>
  </plugin>

Tags

By default the plugin will not generate any tags. You can optionally provide tags using the <tags /> element. Here is an example:

  <plugin>
    <groupId>io.github.berkleytechnologyservices</groupId>
    <artifactId>restdocs-spec-maven-plugin</artifactId>
    <version>${restdocs-spec.version}</version>
    <executions>
      <execution>
        <goals>
          <goal>generate</goal>
        </goals>
        <configuration>
          <tags>
            <tag>
              <name>pets</name>
              <description>Everything about your Pets</description>
            </tag>
            <tag>
              <name>store</name>
              <description>Access to Petstore orders</description>
            </tag>
          </tags>
        </configuration>
      </execution>
    </executions>
  </plugin>

OAuth2 Configuration

By default the plugin will not generate any security information. You can optionally provide it using the <oauth2 /> element. Here is an example:

  <plugin>
    <groupId>io.github.berkleytechnologyservices</groupId>
    <artifactId>restdocs-spec-maven-plugin</artifactId>
    <version>${restdocs-spec.version}</version>
    <executions>
      <execution>
        <goals>
          <goal>generate</goal>
        </goals>
        <configuration>
          <oauth2>
            <tokenUrl>http://example.com/uaa/token</tokenUrl>
            <authorizationUrl>http://example.com/uaa/authorize</authorizationUrl>
            <flows>
              <flow>accessCode</flow>
              <flow>implicit</flow>
            </flows>
            <scopes>
              <scope>
                <name>read</name>
                <description>Access to read operations.</description>
              </scope>
              <scope>
                <name>write</name>
                <description>Access to write operations.</description>
              </scope>
            </scopes>
          </oauth2>
        </configuration>
      </execution>
    </executions>
  </plugin>

Example

You can find a full example project here: https://github.com/BerkleyTechnologyServices/restdocs-spec-example

Still in development

• Support for additional specification formats is currently in development. We plan to add support for Postman Collections and RAML.