JarCastingapikana-java
The java side of apikana.
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.
If you don't like npm, just take advantage of the provided parent pom and use this as a template:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.swisspush.apikana</groupId>
<artifactId>apikana-parent</artifactId>
<version>0.4.14</version>
</parent>
<groupId>myorg.myproject</groupId>
<artifactId>myapi</artifactId>
<version>0.0.1-SNAPSHOT</version>
</project>
Create src/openapi/api.yaml
paths:
/sample/users:
get:
operationId: getUser
responses:
200:
description: ok
schema:
$ref: "#/definitions/User"
definitions:
$ref:
- ../ts/user.ts
And create src/ts/user.ts
import {Int} from 'apikana/default-types';
export interface User {
id: Int
firstName: string // The given name
lastName: string // the family name @pattern [A-Z][a-z]*
age?: Int
}
Create the API documentation
Running mvn install on an API project does the following things:
- create
myapi.jarcontaining the typescript models, the generated json schemas and the generated java pojos. - create
myapi-api.jar, an executable jar file which opens a browser showing the HTML documentation of the API. - start a small HTTP server publishing the HTML documentation of the API at
http://localhost:8333.
Plugin documentation
There is a complete documentation of the maven plugin.
Development
The development is done in the develop branch. Releasing is done by defining the release and new development version in release.sh and by rebasing the develop branch onto the master branch. Travis CI will then pick this up and perform the release.
