thwint/apikana

Integrated tools for REST and Messaging API design - ｱﾋﾟ

A swisspush project

Apikana

Integrated tools for REST and Messaging API design.

Apikana combines the following tools to facilitate the authoring of contract-first REST APIs:

• Swagger
• typescript-json-schema
• Docson

It basically generates formal schemas and documentation from a mixed swagger/typescript definition that is easy to author and maintain.

It supports also java:

• Generate java types (thanks to jsonschema2pojo).

Serialization/Deserialization of java objects:

• The implementation needs a jackson module for serializing and deserializing the objects as described here.

Usage

Create a new API project

Install apikana npm install -g apikana. Run apikana init.

This starts an interactive wizard that lets you define the main aspects of the API project.

Use as a global tool

When apikana start is executed, it looks in src/openapi for a file named api.yaml. This is an OpenAPI 2.0 file defining the REST API. In the definitions section a $ref can be given which references typescript file(s) defining the data models. $ref can be a comma or newline separated string or an array thereof. The models should be defined as typescript export interfaces.

At the end, the dist directory contains the json schemas and a complete HTML documentation of the API. Just open a browser at http://localhost:8333.

src/openapi/api.yaml

paths:
  /sample/users:
    get:
      operationId: getUser
      responses:
        200:
          description: ok
          schema:
            $ref: "#/definitions/User"
definitions:
  $ref: ../ts/user.ts

src/ts/user.ts

export interface User {
    id: number
    firstName: string // The given name
    lastName: string // the family name @pattern [A-Z][a-z]*
    age?: number
}

Annotations like @pattern can be used to specify more precise constraints. They correspond to the JSON Schema validation keywords.

The src/style directory can contain css and image files which can be used to style the generated HTML document.

The gen directory contain the generated files relative to the enabled plugins. This files can be overwritten by defining a templates directory in the root folder of the project using the following directory structure: root_directory/templates/plugin_name/gen/plugin_name/filename.ext where:

• root_directory is the root directory of the project,
• plugin_name is the plugin name (for example maven or dotnet) and
• filename.ext is the file to copy in the gen directory (for example pom.xml or api.csproj).

Matching filenames will be overwritten. All others will be copied in the gen directory.

Use as a devDependency

Instead of being globally installed, apikana can also be defined as a devDependency of a project. A sample configuration would look like:

{
  "name": "My API project",
  "scripts": {
    "start": "apikana start src"
  },
  "devDependencies": {
    "apikana": "0.7.1"
  }
}

Then simply run npm run start.

Development

Development is done within feature branches in forked repositories. When ready it gets merged to swisspush/develop via merge request (at best including review).

Testing

You can run tests using npm test within projects root directory.

Releasing

Releasing is done by updating the version with npm version patch|minor|major and merging develop into master. Then Travis CI will notice the changes on master and perform the release.

Publishing

To publish to npmjs.org, environment variable NPM_TOKEN must be set. You can accomplish this by executing npm login locally and afterwards extracting corresponding value from ~/.nmprc.