cobigen openapiplugin

Table of Contents

• OpenApi Plug-in
  • Trigger Extensions
    • Matcher type
    • ContainerMatcher type
    • VariableAssignment types
    • Full trigger configuration
  • Input reader
  • Merger extensions
  • Usage
    • Writing OpenApi 3.0 contract file
    • Paths
    • Full example

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 'extension' → Extraction of the info extensions and the extensions of each entity. (the tags that start with "x-…​").

    <trigger id="..." type="openapi" templateFolder="...">
      <containerMatcher type="element" value="OpenAPIFile"/>
      <matcher type="element" value="EntityDef">
        <variableAssignment type="extension" key="testingAttribute" value="x-test"/>
        <variableAssignment type="extension" key="rootPackage" value="x-rootpackage"/>
        <variableAssignment type="extension" key="globalVariable" value="x-global"/>
      </matcher>
    </trigger>

The 'extension' variable assignment tries to find 'extensions' (tags that start with "x-…​") on the 'info' part of your file and on the extensions of each entity. value is the extension that our plug-in will try to find on your OpenAPI file. The result will be stored in the variable key.

As you will see on the figure below, there are two types of variables: The global ones, that are defined on the 'info' part of the file, and the local ones, that are defined inside each entity.

Therefore, if you want to define the root package, then you will have to declare it on the 'info' part. That way, all your entities will be generated under the same root package.

If no extension with that name was found, then an empty string will be assigned.

• 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>

The 'property' variable assignment tries to find the property value of the entities defined on the schema. The value is assigned to the key. The current properties that you will able to get are:

1. ComponentDef component: It is an object that stores the configuration of an devon4j component. Its only property is List<PathDef> paths which contains the paths as the ones shown here.

2. String componentName: Stores the name of the x-component tag for this entity.

3. String name: Name of this entity (as shown on the example above).

4. String description: Description of this entity.

5. List<PropertyDef> properties: List containing all the properties of this entity. PropertyDef is an object that has the next properties:

   1. String name.

   2. String type.

   3. String format.

   4. String description.

   5. Boolean isCollection.

   6. Boolean isEntity.

   7. Boolean required.

   8. Map<String, Object> constraints

If no property with that name was found, then it will be set to null.

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>

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)

  • header ('HeaderDef' :: Definition of the header found at the top of the file)

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

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

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

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

  • properties ('List<PropertyDef>' :: List of properties the entity has)

  • relationShips ('List<RelationShip' :: List of Relationships the entity has)

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

  • info ('InfoDef' :: Definition of the info found in the header)

  • servers ('List<ServerDef>' :: List of servers the specification uses)

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

  • title ('String' :: The title of the specification)

  • description ('String' :: The description of the specification)

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

  • URI ('String' :: String representation of the Server location)

  • description ('String' :: description of the server)

• 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 property is set as required)

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

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

  • type ('String' :: type of the relationship (OneToOne, ManyToMany, etc…​))

  • entity ('String' :: destination entity name)

  • sameComponent ('boolean' :: true if the destination entity belongs to the same component of the source entity, false by default)

  • unidirectional ('boolean' :: true if the relationship is unidirectional, false by default)

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

  • pathURI ('String' :: Uri of the path)

  • version ('String' :: version of the service)

  • operations ('List<OperationDef>' :: List of operations for this path)

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

  • type ('String' :: type of the operation (GET, PUT, etc…​))

  • parameters ('List<ParameterDef>' :: List of parameters)

  • operationId ('String' :: name of the operation prototype)

  • description ('String' :: JavaDoc Description of the operation)

  • summary ('List<PropertyDef>' :: JavaDoc operation Summary)

  • tags ('List<String>' :: List of diferent tags)

  • responses ('List<ResponseDef>' :: Responses of the operation)

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

  • isSearchCriteria ('boolean' :: true if the response is an SearchCriteria object)

  • inPath ('boolean' :: true if this parameter is contained in the request path)

  • inQuery ('boolean' :: true if this parameter is contained in a query)

  • isBody ('boolean' :: true if this parameter is a response body)

  • inHeader ('boolean' :: true if this parameter is contained in a header)

  • mediaType ('String' :: String representation of the media type of the parameter)

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

  • isArray ('boolean' :: true if the type of the response is an Array)

  • isPaginated ('boolean' :: true if the type of the response is paginated)

  • isVoid ('boolean' :: true if there is no type/an empty type)

  • isEntity ('boolean' :: true if the type of the response is an Entity)

  • entityRef ('EntityDef' :: Incomplete EntityDef containing the name and properties of the referenced Entity)

  • type ('String' :: String representation of the attribute’s value)

  • code ('String' :: String representation of the HTTP status code)

  • mediaTypes ('List<String>' :: List of media types that can be returned)

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

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>

Usage

Writing OpenApi 3.0 contract file

The Swagger file must follow the OpenApi 3.0 standard to be readable by CobiGen, otherwise and error will be thrown. A full documentation about how to follow this standard can be found Swagger3 Docs.

The Swagger file must be at the core folder of your devon4j project, like shown below:

To be compatible with CobiGen and devon4j, it must follow some specific configurations. This configurations also allows to avoid redundant definitions as SearchCriterias and PaginatedList objects are used at the services definitions.

Paths

• Just adding the tags property at the end of the service definitions with the items SearchCriteria and/or paginated put into CobiGen knowledge that an standard devon4j SearchCriteria and/or PaginateListTo object must be generated. That way, the Swagger file will be easier to write and even more understandable.

• The path must start with the component name, that way this operation would be included into the component services list.

/componentnamemanagement/v1/entityname/customOperation/:
  post:
    summary: 'Summary of the operation'
    description: Description of the operation.
    operationId: customOperation
    responses:
      '200':
        description: Description of the response.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/EntityName'
    requestBody:
      $ref: '#/components/requestBodies/EntityName'
    tags:
      - searchCriteria
      - paginated

Full example

This example yaml file can be download from here.

Warning

As you will see on the file, "x-component" tags are obligatory. They have to be defined for each component (entity). In addition, you will find the global variable "x-rootpackage" that are explained here.

openapi: 3.0.0
servers:
  - url: 'https://localhost:8081/server/services/rest'
    description: Just some data
info:
  title: Devon Example
  description: Example of a API definition
  version: 1.0.0
  x-rootpackage: com.capgemini.spoc.openapi
paths:
  /shopmanagement/v1/shop/{shopId}:
    get:
      operationId: findShop
      parameters:
        - name: shopId
          in: path
          required: true
          schema:
            type: integer
            format: int64
            minimum: 0
            maximum: 50
      responses:
        '200':
          description: Any
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shop'
            text/plain:
              schema:
                type: string
        '404':
          description: Not found
  /salemanagement/v1/sale/{saleId}:
    get:
      operationId: findSale
      parameters:
        - name: saleId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Any
  /salemanagement/v1/sale/{bla}:
    get:
      operationId: findSaleBla
      parameters:
        - name: bla
          in: path
          required: true
          schema:
            type: integer
            format: int64
            minimum: 10
            maximum: 200
      responses:
        '200':
          description: Any
  /salemanagement/v1/sale/:
    post:
      responses:
        '200':
          description: Any
      requestBody:
        $ref: '#/components/requestBodies/ShopData'
      tags:
       - searchCriteria
  /shopmanagement/v1/shop/new:
    post:
      responses:
       '200':
          description: Any
      requestBody:
        $ref: '#/components/requestBodies/ShopData'
components:
    schemas:
        Shop:
          x-component: shopmanagement
          description: Entity definiton of Shop
          type: object
          properties:
            shopExample:
              type: string
              maxLength: 100
              minLength: 5
              uniqueItems: true
          x-manytomany: Shop
          x-onetoone: Sale
        Sale:
          x-component: salemanagement
          description: Entity definiton of Shop
          type: object
          properties:
            saleExample:
              type: number
              format: int64
              maximum: 100
              minimum: 0
          x-onetoone: Shop
          x-onetomany: Shop
          required:
            - saleExample

    requestBodies:
        ShopData:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shop'
          required: true