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 interface
s.
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 examplemaven
ordotnet
) and -
filename.ext
is the file to copy in thegen
directory (for examplepom.xml
orapi.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.13
as release candidates. This old buggy behavior can be restored by configuring a setting in the generated stream apipackage.json
file:// 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:
orBREAKING
in a message), merging tomaster
will 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
.