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 extract 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: v13
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: v13
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 generated properties file is api.properties. it is configurable using the server-url:properties-name option.

openapi-processor-mapping: v13

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 create 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: v13

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

The consequence of the new layout is that for compilation it is necessary to update the configuration 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: v13

options:
  # ... other options

  target-dir:
    layout: standard

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