Integrated tools for REST API design - アピ
Clone or download
Pull request Compare This branch is even with lbovet:master.
Martin Meyer and lbovet [#26] Fixed required field bug
- Empty array is not allowed for required attribute -> must be undefined if there are no required fields
Latest commit e3d8abb Jul 30, 2018

README.md

A swisspush project

# Apikana Integrated tools for REST API design.

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

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

It supports also java:

See it in action in apikana-sample.

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 src 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
}

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

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.4.13"
  }
}

Then simply run npm start.

Development

The development is done in the develop branch. Releasing is done by updating the version with npm version patch|minor|major and by rebasing the develop branch onto the master branch. Travis CI will then pick this up and perform the release. To publish to npmjs.com, the environment variable NPM_TOKEN must be set. Do this by executing npm login locally and the take the corresponding value out of ~/.nmprc.