apigen

API Layer Generator from the OpenAPI specification.

This project is using the OpenAPI Generator and provides a set of plugins for it. Primary target is a golang, however other languages to be considered in the future.

Project status: pre-alpha.

TODOs

General

• Installation and usage instructions
• Documentation on generated code structure and suggested patterns

Golang

• enums
• simple types directly in body
• array types directly in body
• allow handling as plain http handler
• authentication
• per route middleware
• polymorphic models

Typescript

Set of features compatible with golang

Supported OpenAPI features

Some language specific features may be challenging (if possible) to implement correctly. The Language specific caveats summarises various implementation details.

Parameter Serialization

OpenAPI Spec Reference

Supported serialization styles:

parameter location	style	explode	example primitive type	example array type	object support
path	simple	false	/users/5	/users/3,4,5	-
query	form	true	/users?id=5	/users?id=3&id=4&id=5	-

Data types

All types

type	required	nullable
string	✓	✓
number/integer	✓	✓
boolean	✓	✓
object	✓	✓
array	✓	✓

Strings

format	in	minLength	maxLength	pattern
none or custom	query,path,body	✓	✓	✓
date	query,path,body	-	-	-
date-time	query,path,body	-	-	-
byte	query,path,body	✓	✓	-

Numeric data types

type	format	in	minimum	maximum
number	-	query,path	✓	✓
number	float	query,path,body	✓	✓
number	double	query,path,body	✓	✓
integer	-	query,path,body	✓	✓
integer	int32	query,path,body	✓	✓
integer	int64	query,path,body	✓	✓

Boolean

type	in	supported?
boolean	query,path,body	✓

Objects

Objects are only supported in request body of application/json content type.

Arrays

items type	in	minItems	maxItems
string	query,path,body	✓	✓
number	query,path,body	✓	✓
integer	query,path,body	✓	✓
boolean	query,path,body	✓	✓
object	body	✓	✓

Language specific caveats

Golang:

• date type in request body is parsed as time.Time RFC3339Nano
• required in request body has the following constraints:
  • The required check on booleans in request body is not performed
  • For simple data types - will validate if the field is non default
  • For objects - optional and nullable are synonyms. This means that required validation will only work for non nullable fields.
• array fields
  • required is equivalent to minItems: 1
  • nullable arrays are only supported in request body
  • nullable and optional array fields are synonyms

Contributing

Please have the following tools installed:

• direnv
• gobrew
• make
• Java 11 runtime at a minimum

Review Customization docs of openapi generator cli.

Build particular generator:

mvn -f generators/go-apigen-server/ package

Generate code using a particular generator (will build if needed):

make generate/golang

Run tests

make tests