Restful Notes Spring Hateoas Sample

A RESTful web service for creating and storing notes. It uses hypermedia to describe the relationships between resources and to allow navigation between them. Demonstrates using Spring REST Docs with MockMvc and Spring HATEOAS.

Building the Sample

You will need Java 17 to build the sample. It is built using Gradle:

./gradlew build

As part of the build, files named build/docs/asciidoc/api-guide.html and build/docs/asciidoc/getting-started-guide.html are created. They are produced using Asciidoctor and include snippets generated by the sample’s tests using Spring REST Docs.

Building OpenAPI 2.0

In order to generate an OpenAPI 2.0 specification we use the openapi task:

./gradlew openapi

For our project this creates a openapi.yaml file in the output directory (build/api-spec).

Building OpenAPI 3.0

In order to generate an OpenAPI 3.0 specification we use the openapi3 task:

./gradlew openapi3

For our project this creates a openapi3.yaml file in the output directory (build/api-spec).

Building Postman Collection

In order to generate a Postman collection we use the postman task:

./gradlew postman

For our project this creates a postman-collection.json file in the output directory (build/api-spec).

OpenAPI Configurations

Common OpenAPI configuration

The restdocs-api-spec-gradle-plugin takes the following configuration options for OpenAPI 2.0 and OpenAPI 3.0.1 - all are optional.

Name	Description	Default value
title	The title of the application. Used for the title attribute in the Info object	API documentation
description	A description of the application. Used for the description attribute in the Info object	empty
version	The version of the api. Used for the version attribute in the Info object	project version
format	The format of the output OpenAPI file - supported values are json and yaml	json
tagDescriptionsPropertiesFile	A yaml file mapping tag names to descriptions. These are populated into the top level ` Tags attribute	no default - if not provided no tags created.
oauth2SecuritySchemeDefinition	Closure containing information to generate the securityDefinitions object in the OpenAPI specification.	empty
oauth2SecuritySchemeDefinition.flows	The Oauth2 flows the API supports. Use valid values from the securityDefinitions specification.	no default - required if oauth2SecuritySchemeDefinition is set.
oauth2SecuritySchemeDefinition.tokenUrl	The Oauth2 tokenUrl	no default - required for the flows password, application, accessCode.
oauth2SecuritySchemeDefinition.authorizationUrl	The Oauth2 authorizationUrl	no default - required for the flows implicit, accessCode.
oauth2SecuritySchemeDefinition.scopeDescriptionsPropertiesFile	A yaml file mapping scope names to descriptions. These are used in the securityDefinitions as the scope description	no default - if not provided the scope descriptions default to No description.

The scopeDescriptionsPropertiesFile is supposed to be a yaml file:

scope-name: A description

OpenAPI 2.0

The restdocs-api-spec-gradle-plugin takes the following configuration options for OpenAPI 2.0 - all are optional.

Name	Description	Default value
host	The host serving the API - corresponds to the attribute with the same name in the [OpenAPI root object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swagger-object)	`localhost`
basePath	The base path on which the API is served - corresponds to the attribute with the same name in the [OpenAPI root object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swagger-object)	null
schemes	The supported transfer protocols of the API - corresponds to the attribute with the same name in the [OpenAPI root object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swagger-object)	`['http'"]`
outputFileNamePrefix	The file name prefix of the output file.	`openapi` which results in e.g. `openapi.json` for the format `json`

Example configuration closure:

openapi {
    basePath = "/api"
    host = "api-shop.beyondshop.cloud"
    schemes = ["https"]
    format = "yaml"
    title = 'Beyond REST API'
    version = "1.0.0"
    separatePublicApi = true
    snippetsDirectory="src/docs/asciidoc/generated-snippets/"
    outputDirectory="openapi/"
    oauth2SecuritySchemeDefinition = {
        flows = ['accessCode', 'application']
        tokenUrl = 'https://api-shop.beyondshop.cloud/api/oauth/token'
        authorizationUrl = 'https://api-shop.beyondshop.cloud/api/auth/oauth-ext/authorize'
        scopeDescriptionsPropertiesFile = "src/docs/scope-descriptions.yaml"
    }
}

OpenAPI 3.0.1

The restdocs-api-spec-gradle-plugin takes the following configuration options for OpenAPI 3.0.1 - all are optional.

Name	Description	Default value
outputFileNamePrefix	The file name prefix of the output file.	`openapi3` which results in e.g. `openapi3.json` for the format `json`
servers	Specifies the servers the API is available from. Use this property to specify multiple server definitions. See example below.	`http://localhost`
server	Specifies the servers the API is available from. Use this property to specify just a single server definition. See example below	`http://localhost`

Example configuration closure:

openapi3 {
    servers = [ { url = "http://some.api" } ]
    title = 'My API title'
    version = '1.0.1'
    format = 'yaml'
    contact = {
        name = 'John Doe'
        email = 'john.doe@example.com'
    }
    separatePublicApi = true
    outputFileNamePrefix = 'my-api-spec'
    oauth2SecuritySchemeDefinition = {
        flows = ['authorizationCode']
        tokenUrl = 'http://example.com/token'
        authorizationUrl = 'http://example.com/authorize'
        scopeDescriptionsPropertiesFile = "scopeDescriptions.yaml"
    }
}

The servers and server property can also contain variables. Is this case the` property can be specified like this:

This configuration follows the same semantics as the ['Servers Object'](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#server-object) in the OpenAPI specification

servers = [ {
    url = 'https://{host}/api'
    variables = [
        host: [
            default: 'api-shop.beyondshop.cloud/api',
            description: 'The hostname of your beyond shop',
            enum: ['api-shop', 'oz']
        ]
    ]
} ]

The same structure applies to server. A single server can also be specified using a plain string:

server = 'http://some.api/api'

Postman

The restdocs-api-spec-gradle-plugin takes the following configuration options for Postman collections - all are optional.

Name	Description	Default value
title	The title of the application. Used for the `name` attribute of the `Information` object of the collection	`API documentation`
version	The version of the api. Used for the `version` attribute in the `Information` object	project version if specified - otherwise `1.0.0`
baseUrl	The baseUrl of the application. e.g. `https://myapi.example.com:8080/api`	`http://localhost`

Example configuration closure:

postman {
    title = 'Beyond REST API'
    version = '1.0.1'
    baseUrl = 'https://api-shop.beyondshop.cloud/api'
    separatePublicApi = true
    outputFileNamePrefix = 'my-postman-collection'
}

Generate an HTML-based API reference from OpenAPI

We can use [redoc](https://github.com/Rebilly/ReDoc) to generate an HTML API reference from our OpenAPI specification.

The [redoc-cli](https://www.npmjs.com/package/redoc-cli) can be used to bundle (and serve) this API reference:

# Bundle the documentation into a zero-dependency HTML-file
npx @redocly/cli build-docs build/api-spec/openapi.json

# Bundle and serve
npx @redocly/cli preview-docs build/api-spec/openapi.json

ebi-gene-expression-group/restful-notes-spring-hateoas-demo

Restful Notes Spring Hateoas Sample

Building the Sample

Building OpenAPI 2.0

Building OpenAPI 3.0

Building Postman Collection

OpenAPI Configurations

Common OpenAPI configuration

OpenAPI 2.0

OpenAPI 3.0.1

Postman

Generate an HTML-based API reference from OpenAPI