Skip to content

cobigen openapiplugin

Jump to bottom Edit New page
Jaime Diaz edited this page Apr 25, 2019 · 23 revisions

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 thought to follow a "code first" generation, with this plugin, now it can also follow 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…​

Note
 If you are not a CobiGen developer, you will be more interested in usage.

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 (e.g. com.devonfw.project).

Swagger at devon4j Project

If no extension with that name was found, then an empty string will be assigned. In the case of not defining the root package, then the code will be generated into src/main/java.

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

Swagger at devon4j Project

To be compatible with CobiGen and devon4j, it must follow some specific configurations. This configurations allows us 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, and define an x-component tag with the component name. That way this service will be included into the component services list.

/componentnamemanagement/v1/entityname/customOperation/:
  x-component: componentnamemanagement
  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

That way, CobiGen will be able to generate the endpoint (REST service) customOperation on componentmanagement. If you do not specify the component to generate to (the x-component tag) then this service will not be taken into account for generation.

Service based generation

In previous CobiGen versions, we were able to generate code from a contract-first OpenApi specification only when we defined components like the following:

components:
    schemas:
        Shop:
          x-component: shopmanagement
          description: Entity definiton of Shop
          type: object
          properties:
            shopExample:
              type: string
              maxLength: 100
              minLength: 5
              uniqueItems: true

We could not generate services without the definition of those components.

In our current version, we have overcomed it, so that now we are able to generate all the services independently. You just need to add an x-component tag with the name of the component that will make use of that service. See here.

An small OpenAPI example defining only services can be found below:

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:
  /salemanagement/v1/sale/{saleId}:
    x-component: salemanagement
    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}:
    x-component: salemanagement
    get:
      operationId: findSaleBla
      parameters:
        - name: bla
          in: path
          required: true
          schema:
            type: integer
            format: int64
            minimum: 10
            maximum: 200
      responses:
        '200':
          description: Any

Then, the increment that you need to select for generating those services is Crud devon4ng Service based Angular:

Service based generation

Full example

This example yaml file can be download from here.

Warning
 As you will see on the file, "x-component" tags are obligatory if you want to generate components (entities). They have to be defined for each one. 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.devonfw.angular.test
paths:
  /shopmanagement/v1/shop/{shopId}:
    x-component: shopmanagement
    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}:
    x-component: salemanagement
    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/:
    x-component: salemanagement
    post:
      responses:
        '200':
          description: Any
      requestBody:
        $ref: '#/components/requestBodies/SaleData'
      tags:
       - searchCriteria
  /shopmanagement/v1/shop/new:
    x-component: shopmanagement
    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
            sales:
              type: array # Many to One relationship
              items:
                $ref: '#/components/schemas/Sale'
        Sale:
          x-component: salemanagement
          description: Entity definiton of Shop
          type: object
          properties:
            saleExample:
              type: number
              format: int64
              maximum: 100
              minimum: 0
          required:
            - saleExample

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

Disclaimer

If you discover any documentation bugs or would like to request new content, please raise them as an issue or create a pull request. Contributions to this wiki are done through the main repo under the folder documentation.

License

88x31

Eclipse Integration

Clone this wiki locally