Server Url

base path

OpenAPI offers a servers section to describe the server urls available to access the api.

openapi-processor has (simple) support to generate a resource property file with the path of a server url. The processor will resolve all variables with their default value and extracts the urls path.

Given an OpenAPI description with a servers key:

openapi: 3.1.0
info:
  title: server url example
  version: 1.0.0

servers:
  - url: "https://openapiprocessor.io/{path}"
    variables:
      path:
        default: api
# ...

and a mapping

openapi-processor-mapping: v9
options:
  server-url: true

it will generate a simple resource properties file with a single property openapi.base.path:

# api.properties
openapi.base.path = /api

If there are multiple servers its index can be used to select it:

openapi-processor-mapping: v9
options:
  server-url: 0   # same as true
#  server-url: 1
#  server-url: 2

using the generated properties file

The properties file is used to configure Spring Boots server.servlet.context-path:

# application.properties

#spring.config.import = api.properties
server.servlet.context-path=${openapi.base.path}

While it is possible to import the generated properties file it is probably better to simply use the generated properties as an additional profile.

name of the properties file

The default name of the generate properties file is api.properties. it is configurable using the server-url:properties-name option.

openapi-processor-mapping: v9

options:
  server-url:
    properties-name: base-path.properties

destination directory

By default, the processor will generate the java package structure directly below the targetDir. To creates the resource file it needs a second (resources) directory as target directory.

This is handled by a new option to set the layout of the targetDir. Setting it to standard

openapi-processor-mapping: v9

options:
  target-dir:
    layout: standard

will create the following directory layout:

targetDir
+--- java
|      \--- io
|           \--- openapiprocessor
|                +--- api
|                \--- model
\--- resources

and write the properties file to the resources directory.

To have a destination directory for generating the resource file, setting server-url to a truthy value will automatically enable the standard target dir layout. It is still recommended to set it explicitly for documentation.

build configuration

Consequence of the new layout is that for compilation it is necessary to update configure of the sources and resources directories in the build configuration.

For example with gradle the sourceSets configuration would change to something like this:

sourceSets {
    main {
        java {
            // add generated files
            srcDir(layout.buildDirectory.dir("openapi/java"))
        }
        resources {
            // add generated resources
            srcDir(layout.buildDirectory.dir("openapi/resources"))
        }
    }
}

options summary

Here is a short snippet of a mapping.yaml as a summary of the options used to configure the base path property file generation.

openapi-processor-mapping: v9

options:
  # ... other options

  target-dir:
    layout: standard

  base-path:
    server-url: 0
    properties-name: base-path.properties