https://github.com/berkleytechnologyservices/restdocs-spec

A maven plugin for generating Open API and Postman Collection specifications using Spring Restdocs.
https://github.com/berkleytechnologyservices/restdocs-spec

api-documentation maven maven-plugin openapi spring-rest-docs swagger

Last synced: 9 days ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/berkleytechnologyservices/restdocs-spec
• Owner: BerkleyTechnologyServices
• License: apache-2.0
• Created: 2018-08-23T13:59:20.000Z (over 6 years ago)
• Default Branch: master
• Last Pushed: 2024-10-29T00:13:12.000Z (about 2 months ago)
• Last Synced: 2024-10-29T15:11:13.470Z (about 2 months ago)
• Topics: api-documentation, maven, maven-plugin, openapi, spring-rest-docs, swagger
• Language: Java
• Homepage:
• Size: 382 KB
• Stars: 56
• Watchers: 10
• Forks: 18
• Open Issues: 11
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# Restdocs Spec Generation Support

[![Build Status](https://github.com/BerkleyTechnologyServices/restdocs-spec/workflows/CI/badge.svg?branch=master&event=push)](https://github.com/BerkleyTechnologyServices/restdocs-spec/actions?query=branch%3Amaster+workflow%3ACI)

[![Maven Central](https://img.shields.io/maven-central/v/io.github.berkleytechnologyservices/restdocs-spec)](https://central.sonatype.com/search?q=a%253Arestdocs-spec%2520g%253Aio.github.berkleytechnologyservices&namespace=io.github.berkleytechnologyservices)

## Usage

First head over to the [ePages-de/restdocs-api-spec](https://github.com/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:

```xml

  

    io.github.berkleytechnologyservices

    restdocs-spec-maven-plugin

    ${restdocs-spec.version}

    

      

        

          generate

        

      

    

  

```

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:

```xml

  

    io.github.berkleytechnologyservices

    restdocs-spec-maven-plugin

    ${restdocs-spec.version}

    

      

        

          generate

        

        

          JSON

        

      

    

  

```

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

```xml

  

    io.github.berkleytechnologyservices

    restdocs-spec-maven-plugin

    ${restdocs-spec.version}

    

      

        

          generate

        

        

          OPENAPI_V3

        

      

    

  

```

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

```xml

  

    io.github.berkleytechnologyservices

    restdocs-spec-maven-plugin

    ${restdocs-spec.version}

    

      

        

          generate

        

        

          

            

              OPENAPI_V2

            

            

              OPENAPI_V3

              JSON

            

            

              POSTMAN_COLLECTION

              my-api-collection

            

          

        

      

    

  

```

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

```xml

  

    io.github.berkleytechnologyservices

    restdocs-spec-maven-plugin

    ${restdocs-spec.version}

    

      

        

          generate

        

        

          ${project.artifactId}

          ${project.version}

          localhost

          

          

            http

          

          ${project.build.directory}/generated-snippets

          OPENAPI_V2

          ${project.build.directory}/restdocs-spec

          false

          YAML

          openapi-2.0

          false

          

          

        

      

    

  

```

### Tags

By default the plugin will not generate any tags.  You can optionally provide tags using the

 `` element.  Here is an example:

```xml

  

    io.github.berkleytechnologyservices

    restdocs-spec-maven-plugin

    ${restdocs-spec.version}

    

      

        

          generate

        

        

          

            

              pets

              Everything about your Pets

            

            

              store

              Access to Petstore orders

            

          

        

      

    

  

```

### OAuth2 Configuration

By default the plugin will not generate any security information.  You can optionally provide

it using the `` element.  Here is an example:

```xml

  

    io.github.berkleytechnologyservices

    restdocs-spec-maven-plugin

    ${restdocs-spec.version}

    

      

        

          generate

        

        

          

            http://example.com/uaa/token

            http://example.com/uaa/authorize

            

              accessCode

              implicit

            

            

              

                read

                Access to read operations.

              

              

                write

                Access to write operations.

              

            

          

        

      

    

  

```

## 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.