View on GitHub

Microservice DSL (MDSL)

A Domain-Specific Language (DSL) to specify (micro-)service contracts, their data representations and API endpoints.

Tools Overview, Protocol Buffers, GraphQL, Jolie, Java, Freemarker templating, AsyncAPI

OpenAPI Specification Generator

The MDSL Eclipse plugin and the CLI allow API designers to generate OpenAPI specifications out of MDSL service contracts.

Usage

You can generate the OpenAPI specifications from MDSL models via the Eclipse plugin or the CLI.

In Eclipse, you find the generator in the MDSL context menu:

OpenAPI Specification Generator Context Menu in Eclipse

The following command generates a specification in case you work with the CLI:

./mdsl -i model.mdsl -g oas

Hint: Both tools generate the output into the src-gen folder which is located in the projects root directory (Eclipse) or the directory from which the mdsl command has been called (CLI). Both tools create the directory automatically in case it does not already exist. Look for .yaml files corresponding to the .mdsl input.

Generator Output / Mapping

The OpenAPI Specification (OAS) generator maps endpoint types to HTTP resource paths, and operations to HTTP methods/verbs like this:

If an HTTP verb appears more than once, for instance if more than five operations are defined, the information in the expecting part of the endpoint type is not sufficient to define a single HTTP resource API. An HTTP binding with multiple resources has to be defined in that case (see the bindings page for an example of a resource definition).

The input data in MDSL are mapped differently, depending on the HTTP method/verb (which is mapped as explained above). The following table explains the mapping:

HTTP Methods MDSL Data Type OAS/HTTP Parameter Type Mapping
GET Atomic Parameter "pname":D<string> query, cookie, header supported, simple
  Atomic Parameter List ("p1":D<string>, "p2":D<string>) query, cookie, header each element becomes separate parameter
  Flat Parameter Tree {"p1":D<string>, "p2":D<string>} query, cookie , header yes, also flattened
  Nested Parameter Tree {"p1":D<string>, {"t2":D<string>}} query yes (Deep Object)
  any parameter path limited support (TODO)
  any parameter body not supported (by HTTP/OAS)
DELETE same as GET    
POST Atomic Parameter "pname":D<string> query, cookie, header supported, simple
  Atomic Parameter List ("p1":D<string>, "p":D<string>) query, cookie, header supported, simple
  Flat Parameter Tree {"p1":D<string>, "p":D<string>} query, cookie, header supported, simple
  Nested Parameter Tree {"p1":D<string>, {"anotherTree":D<string>}} query  
  any parameter path not recommended (TODO)
  any parameter body default (multiple mime/media types)
PUT, PATCH same as POST    

Response messages delivering are always mapped to the response body. Additional status and error report responses can be defined; multiple media types, including custom ones, are respected if present in the endpoint type (replies).

Note: The above mappings works with MDSL HTTP mappings in the providers. Providers that do not contain an HTTP mapping are ignored.

Example

The following example illustrates what the generator produces for an exemplary MDSL contract.

You find the complete sources (incl. the generated OAS specification) of this example here.

We use the following MDSL model which was an outcome of this blogpost to illustrate our generator outputs:

API description ReferenceManagementServiceAPI

data type PaperItemDTO { "title":D<string>, "authors":D<string>, "venue":D<string>, "paperItemId":PaperItemKey }
data type PaperItemKey { "doi":D<string> }
data type createPaperItemParameter { "who":D<string>, "what":D<string>, "where":D<string> }

endpoint type PaperArchiveFacade
  serves as INFORMATION_HOLDER_RESOURCE
  exposes
    operation createPaperItem
      with responsibility STATE_CREATION_OPERATION
      expecting
        payload createPaperItemParameter
      delivering
        payload PaperItemDTO
    operation lookupPapersFromAuthor
      with responsibility RETRIEVAL_OPERATION
      expecting
        payload "author": D<string>
      delivering
        payload PaperItemDTO*
    operation convertToMarkdownForWebsite
      expecting
        payload PaperItemKey
      delivering
        payload D<string>

For the MDSL contract above, the generator produces the following OAS specification:

openapi: 3.0.1
info:
  title: ReferenceManagementServiceAPI
  version: "1.0"
servers: []
tags:
- name: PaperArchiveFacade
  externalDocs:
    description: The role of this endpoint is Information Holder Resource pattern
    url: https://microservice-api-patterns.org/patterns/responsibility/endpointRoles/InformationHolderResource.html
paths:
  /PaperArchiveFacade:
    summary: general data-oriented endpoint
    get:
      tags:
      - PaperArchiveFacade
      summary: read only
      description: This operation realizes the [Retrieval Operation](https://microservice-api-patterns.org/patterns/responsibility/operationResponsibilities/RetrievalOperation.html)
        pattern.
      operationId: lookupPapersFromAuthor
      parameters:
      - name: author
        in: query
        required: true
        schema:
          type: string
      responses:
        "200":
          description: lookupPapersFromAuthor successful execution
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaperItemDTO'
    put:
      tags:
      - PaperArchiveFacade
      summary: write only
      description: This operation realizes the [State Creation Operation](https://microservice-api-patterns.org/patterns/responsibility/operationResponsibilities/StateCreationOperation.html)
        pattern.
      operationId: createPaperItem
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createPaperItemParameter'
      responses:
        "200":
          description: createPaperItem successful execution
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaperItemDTO'
    post:
      tags:
      - PaperArchiveFacade
      description: unspecified operation responsibility
      operationId: convertToMarkdownForWebsite
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaperItemKey'
      responses:
        "200":
          description: convertToMarkdownForWebsite successful execution
          content:
            application/json:
              schema:
                type: object
                properties:
                  anonymous1:
                    type: string
components:
  schemas:
    PaperItemDTO:
      type: object
      properties:
        title:
          type: string
        authors:
          type: string
        venue:
          type: string
        paperItemId:
          $ref: '#/components/schemas/PaperItemKey'
    PaperItemKey:
      type: object
      properties:
        doi:
          type: string
    createPaperItemParameter:
      type: object
      properties:
        who:
          type: string
        what:
          type: string
        where:
          type: string
  securitySchemes: {}

You find the complete sources (incl. the generated OAS specification) of this example here.

Editor and Validation

You can use the Swagger Editor to validate generated OAS specifications and/or generate an HTML documentation. You can also generate client and server code from there.

Known Limitations

Other Generators

The other generators are:

Site Navigation

Copyright: Stefan Kapferer and Olaf Zimmermann, 2020-2021. All rights reserved. See license information.