A swisspost project
Integrated tools for REST and Messaging 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:
- 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.
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.
Then enter the project directory and run npm install to install all the required dependencies.
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.tssrc/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_directoryis the root directory of the project,plugin_nameis the plugin name (for examplemavenordotnet) andfilename.extis the file to copy in thegendirectory (for examplepom.xmlorapi.csproj).
Matching filenames will be overwritten. All others will be copied in the gen directory.
A note on Java code generation
By default Apikana generates Maven SNAPSHOT version for release candidates (version number of the stream api looks like
1.0.0-rc.3). Due to a bug in Apikana < 0.9.23 it also considered versions like1.0.0-feature-test.13as release candidates. This old buggy behavior can be restored by configuring a setting in the generated stream apipackage.jsonfile:// File package.json { // ... "customConfig": { // ... "snapshotVersion": "ALL_NON_FINAL" // ... } }
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 is done within feature branches in forked repositories. When ready it gets merged to swisspost/develop via merge request (at best including review).
Make sure to comply with the conventional commits specification when writing commit or squash commit messages, as they control the next version when releasing!
You can run tests using npm test within projects root directory.
Releasing is done automatically using semantic-release when merging to develop and master.
Merging to develop will release to the next distribution channel on npm, merging to master will publish that release to the main distribution channel.
IMPORTANT
If the conventional commits result in a new release (i.e. having
feat:,fix:orBREAKINGin a message), merging tomasterwill trigger a new release on npmjs.org automatically without any further user interaction!
To publish to npmjs.org locally, the environment variable NPM_TOKEN must be set. You
can accomplish this by executing npm login locally and afterwards extracting
corresponding value from ~/.nmprc.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent