cobigen openapiplugin

Table of Contents

• OpenApi Plug-in
  • Trigger Extensions
    • Matcher type
    • ContainerMatcher type
    • VariableAssignment types
    • Full trigger configuration
  • OpenApi3 Input reader
  • Merger extensions

OpenApi Plug-in

The OpenApi Plug-in enables the support for Swagger files that follows the OpenApi 3.0 standard as input for CobiGen. Until now, CobiGen was though to follow a "code first" generation, with this plugin, now can follow too the "contract first" strategy

• Code First

  • Generating from a file with code (Java/XML code in our case)

• Contract First

  • Generation from a full definition file (Swagger in this case). This file contains all the information about entities, operations, etc…​

Trigger Extensions

The OpenApi Plug-in provides a new trigger for Swagger OpenApi 3.0 related inputs. It accepts different representations as inputs (see OpenApi input reader) and provides additional matching and variable assignment mechanisms. The configuration in the context.xml for this trigger looks like this:

• type 'openapi'

  Example of a openapi trigger definition

  <trigger id="..." type="openapi" templateFolder="...">
      ...
  </trigger>

  This trigger type enables OpenApi elements as inputs.

Matcher type

With the trigger you might define matchers, which restrict the input upon specific aspects:

• type 'element' → An object

This trigger will be enabled if the element (Java Object) of the input file is and EntityDef (value).

ContainerMatcher type

Additionally, the java plugin provides the ability to match packages (containers) as follows:

• type 'element'

The container matcher matches elements as Java Objects, in this case will be always an OpenApiFile object. (See containerMatcher semantics to get more information about containerMatchers itself.)

VariableAssignment types

Furthermore, it provides the ability to extract information from each input for further processing in the templates. The values assigned by variable assignments will be made available in template and the destinationPath of context.xml through the namespace variables.<key>. The OpenApi Plug-in currently provides two different mechanisms:

• type 'constant' → constant parameter

  <trigger id="..." type="openapi" templateFolder="...">
      <containerMatcher type="element" value="OpenApiFile"/>
      <matcher type="element" value="EntityDef">
          <variableAssignment type="constant" key="rootPackage" value="com.capgemini.demo" />
      </matcher>
  </trigger>

This variable assignment assigns the value of the given regular expression group number to the given key. In this case, the constant type variableAssignment is used to specify the root package where the generate will place the files generated.

• type 'property' → property of the Java Object

  <trigger id="..." type="openapi" templateFolder="...">
      <containerMatcher type="element" value="OpenApiFile"/>
      <matcher type="element" value="EntityDef">
          <variableAssignment type="property" key="entityName" value="name" />
      </matcher>
  </trigger>

This variable assignment assigns the value to the key as a constant.

Full trigger configuration

<trigger id="..." type="openapi" templateFolder="...">
    <containerMatcher type="element" value="OpenApiFile">
    <matcher type="element" value="EntityDef">
        <variableAssignment type="constant" key="rootPackage" value="com.capgemini.demo" />
        <variableAssignment type="property" key="component" value="componentName" />
        <variableAssignment type="property" key="entityName" value="name" />
    </matcher>
</trigger>

OpenApi3 Input reader

The Cobigen OpenApi Plug-in implements an input reader for OpenApi 3.0 files. The XML input reader will create the following object model for template creation:

• model ('Map<String, Object>' :: common element structure)

  • name ('String' :: Name of the current Entity)

  • componentName ('String' :: name oif the component that entity belongs to)

  • component ('ComponentDef' :: Full definition of the component that entity belongs to)

  • description ('String' :: Description of the Entity)

  • properties ('List<PropertyDef>' :: String representation of the attribute’s value)

  • relationShips ('List<RelationShip' :: String representation of the attribute’s value)

• ComponentDef ('Map<String, Object>' :: common element structure)

  • paths ('List<PathDef>' :: List of services for this component)

• PropertyDef ('Map<String, Object>' :: common element structure)

  • name ('String' :: Name of the property)

  • type ('String' :: type of the property)

  • format ('String' :: format of the property (i.e. int64))

  • isCollection ('boolean' :: true if the property is a collection, false by default)

  • isEntity ('boolean' :: true if the property referes to another entity, false by default)

  • sameComponent ('boolean' :: true if the entity that the property refers to belonmgs to the same component, false by default)

  • description ('String' :: Description of the property)

  • required ('boolean' :: true if the proiperty is set as required)

  • constraints ('Map<String, Object>')

 — TODO: update the descriptions

• RelationShip ('Map<String, Object>' :: common element structure)

  • type ('String' :: Name of the current Entity)

  • entity ('String' :: name oif the component that entity belongs to)

  • sameComponent ('ComponentDef' :: Full definition of the component that entity belongs to)

  • unidirectional ('String' :: Description of the Entity)

• PathDef ('Map<String, Object>' :: common element structure)

  • pathURI ('String' :: Name of the current Entity)

  • version ('String' :: name oif the component that entity belongs to)

  • operations ('ComponentDef' :: Full definition of the component that entity belongs to)

• OperationDef ('Map<String, Object>' :: common element structure)

  • type ('String' :: Name of the current Entity)

  • parameters ('String' :: name oif the component that entity belongs to)

  • operationId ('ComponentDef' :: Full definition of the component that entity belongs to)

  • description ('String' :: Description of the Entity)

  • summary ('List<PropertyDef>' :: String representation of the attribute’s value)

  • tags ('List<RelationShip' :: String representation of the attribute’s value)

  • response ('List<RelationShip' :: String representation of the attribute’s value)

• ParameterDef ('Map<String, Object>' :: common element structure)

  • isSearchCriteria ('String' :: Name of the current Entity)

  • inPath ('String' :: name oif the component that entity belongs to)

  • inQuery ('ComponentDef' :: Full definition of the component that entity belongs to)

  • inHeader ('String' :: Description of the Entity)

  • mediaType ('List<PropertyDef>' :: String representation of the attribute’s value)

• ResponseDef ('Map<String, Object>' :: common element structure)

  • isArray ('String' :: Name of the current Entity)

  • isPaginated ('String' :: name oif the component that entity belongs to)

  • isEntity ('ComponentDef' :: Full definition of the component that entity belongs to)

  • isVoid ('String' :: Description of the Entity)

  • type ('List<PropertyDef>' :: String representation of the attribute’s value)

  • format ('List<RelationShip' :: String representation of the attribute’s value)

  • mediaType ('List<RelationShip' :: String representation of the attribute’s value)

Merger extensions

This plugin only provides an input reader, there is no support for OpenApi merging. Nevertheless, the files generated from an OpenApi file will be Java, XML, JSON, TS, etc…​ so, for each file to be generated defined at templates.xml, must set the mergeStartegy for the specific language (javamerge, javamerge_override, jsonmerge, etc…​)

<templates>
    ...
    <templateExtension ref="${variables.entityName}.java" mergeStrategy="javamerge"/>
    ...
    <templateExtension ref="${variables.entityName}dataGrid.component.ts" mergeStrategy="tsmerge"/>
    ...
    <templateExtension ref="en.json" mergeStrategy="jsonmerge"/>
</templates>