The OpenAPI 3.0 specification defines a standard, programming language-agnostic interface description for Web APIs, which allows both humans and computers to discover and understand the capabilities of a Web API.

An OpenAPI definition consists of multiple sections:

  • info (API metadata);

  • servers (base URLs of servers supporting the API);

  • paths (resources and their HTTP methods);

  • tags (used to group path entries);

  • security (security requirements relevant for deployment);

  • components (path/query parameters, schemas, responses).

The schemas sub-section specifies request and response schemas. For data resources, these schemas reuse content schemas, for example, of features in an application schema. Schemas are specified using JSON Schema, either expressed in JSON or YAML.

The methodology for deriving technology-specific encodings of conceptual schemas in UML based on the General Feature Model that is supported by ShapeChange, therefore, has direct application to the generation of OpenAPI content schemas.

A similar methodology can be used to generate documentation for Web APIs.

Building blocks implemented by an API instance that are based on the OGC API specifications are determined by the selection of conformance classes that a given API should support (exclusive of any consideration for tool-specific extensions).

This target can be used to create a minimal OpenAPI definition for a Web API implementing OGC API Features parts 1 and 2, for sections other than for content schemas.

Note
 The initial implementation of this target has been developed in the OGC UGAS-2020 Pilot activity. The Engineering Report (to be published) produced by that project describes the design as well as the process with which an OpenAPI definition is created by the target, in further detail.

1. Configuration

1.1. Class

The class for the target implementation is de.interactive_instruments.ShapeChange.Target.OpenApi.OpenApiDefinition

1.2. Rules

An <EncodingRule> element defines an encoding rule.

Example 1:


  
1
2
3


  
<EncodingRule name="myopenapi">
   <rule name="rule-openapi-all-explicit-collections"/>
</EncodingRule>

The name attribute of the <EncodingRule> element defines the identifier of the encoding rule to be used. The value of the target parameter defaultEncodingRule must contain this name.

The optional extends attribute of the <EncodingRule> element includes all rules from the referenced encoding rule in this encoding rule, too.

Each <rule> references either a conversion rule or - possibly in the future - a requirement or recommendation to be tested during the validation before the conversion process.

The following sections list the rules that are supported by this target.

1.2.1. rule-openapi-all-explicit-collections

A rule for identifying feature collections to add to the OpenAPI definition. With this rule, the feature types are explicitly identified using the target parameter collections. This supports a tailored approach for more complex use cases, and also enables the specification of APIs supporting only a profile of the application schema.

Note
 This rule has higher priority than rule-openapi-cls-instantiable-feature-types and rule-openapi-cls-top-level-feature-types.

1.2.2. rule-openapi-cls-instantiable-feature-types

A rule for identifying feature collections to add to the OpenAPI definition. With this rule, each instantiable feature type is selected, i.e. abstract feature types are skipped.

Note
 This rule has higher priority than rule-openapi-cls-top-level-feature-types, but less priority than rule-openapi-all-explicit-collections.

1.2.3. rule-openapi-cls-top-level-feature-types

A rule for identifying feature collections to add to the OpenAPI definition. With this rule, each top-level feature type is selected, i.e. feature types with a supertype in the same application schema are skipped.

Note
 This rule has less priority than rule-openapi-all-explicit-collections and rule-openapi-cls-instantiable-feature-types.

1.3. Parameters

The <targetParameters> recognized for this target are described in the following sections.

1.3.1. baseTemplate

Alias: none

Required / Optional: optional

Type: String

Default Value: https://shapechange.net/resources/openapi/overlays/default-template.json

Explanation: Reference to a base OpenAPI template (local file or URI).

Applies to Rule(s): none - default behavior

1.3.2. collections

Alias: none

Required / Optional: optional

Type: String (comma-separated list)

Default Value: none

Explanation: Identifies the feature types for which feature collections shall be created in the OpenAPI definition.

Applies to Rule(s): rule-openapi-all-explicit-collections

1.3.3. defaultEncodingRule

Alias: none

Required / Optional: required

Type: String

Default Value: none

Explanation: The identifier of the default encoding rule governing the conversion to an OpenAPI definition. To use a custom encoding rule defined in the configuration, simply provide the name of the custom encoding rule via this parameter.

Applies to Rule(s): none - default behavior

1.3.4. jsonSchemasBaseLocation

Alias: none

Required / Optional: required

Type: URI

Default Value: none

Explanation: Identifies the base directory of the single location where all JSON Schemas for the feature types of the OpenAPI definition are stored.

Applies to Rule(s): none - default behavior

1.3.5. jsonSchemaVersion

Alias: none

Required / Optional: optional

Type: Enum - one of "2019-09", "OpenApi30"

Default Value: "2019-09"

Explanation:Identifies the version of the JSON Schemas created (either manually or by using the ShapeChange JSON Schema target) for the feature types. For an OpenAPI 3.0 definition, the jsonSchemaVersion must be set to "OpenApi30".

Applies to Rule(s): none - default behavior

1.3.6. outputDirectory

Alias: none

Required / Optional: optional

Type: String

Default Value: <the current run directory>

Explanation: The path to the folder in which the resulting OpenAPI file will be created.

Applies to Rule(s): none - default behavior

1.3.7. outputFilename

Required / Optional: Required

Type: String

Default Value: "OpenApiDefinition.json"

Explanation: The name of the OpenAPI file (can be without file extension).

Applies to Rule(s): none – default behavior

1.4. Map Entries

Thus far, no specific map entry parameters have been defined for the OpenAPI target.

1.5. Advanced Process Configuration

The advancedProcessConfigurations element inside of the Target configuration element is used to define the relevant conformance classes and additional query parameters - see the configuration example.

A ConformanceClass element must be added for each applicable conformance class (i.e. at least for the core conformance class). This element has the following attributes:

A QueryParameter element can be added for each non-standard query parameter, that is applicable to the API. This element has the following attributes:

  • name (required): The name of the query parameter.

  • overlay (required): References the overlay file that, when merged into the OpenAPI definition, results in support for the query parameter.

  • appliesToPhase (optional): Identifies the processing phase, in which the overlay shall be merged. Allowed values are "pre-feature-identification" and "finalization". The former means that the overlay is merged before feature type specific updates are applied to the OpenAPI definition during the conversion process, while the latter means that the overlay is merged into the final OpenAPI definition, at the end of the conversion process.

2. Configuration Example


  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


  
<Target class="de.interactive_instruments.ShapeChange.Target.OpenApi.OpenApiDefinition" mode="enabled" inputs="model">
 <advancedProcessConfigurations>
  <OpenApiConfigItems>
   <conformanceClasses>
    <ConformanceClass uri="http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core"/>
    <ConformanceClass uri="http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson"/>
    <ConformanceClass uri="http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/html"/>
    <ConformanceClass uri="http://www.opengis.net/spec/ogcapi-features-2/1.0/conf/crs" param="http://www.opengis.net/def/crs/OGC/1.3/CRS84 http://www.opengis.net/def/crs/EPSG/0/4326 http://www.opengis.net/def/crs/EPSG/0/3395"/>
   </conformanceClasses>
   <queryParameters>
    <QueryParameter name="f" overlay="config/f.json" appliesToPhase="pre-feature-identification"/>
    <QueryParameter name="string" overlay="config/string.json" appliesToPhase="finalization"/>
   </queryParameters>
  </OpenApiConfigItems>
 </advancedProcessConfigurations>
 <targetParameter name="outputDirectory" value="results/openapi"/>
 <targetParameter name="outputFilename" value="openapi.json"/>
 <targetParameter name="jsonSchemasBaseLocation" value="https://example.org/schemas/json"/>
 <targetParameter name="jsonSchemaVersion" value="openapi30"/>
 <targetParameter name="collections" value="FeatureType1, FeatureType2"/>
 <targetParameter name="defaultEncodingRule" value="myopenapi"/>
 <rules>
  <EncodingRule name="myopenapi">
   <rule name="rule-openapi-all-explicit-collections"/>
  </EncodingRule>
 </rules>
</Target>