openapi-eller Manual

A target is the recipe for generating API code for a given platform. It may generate either a client or a server depending on its need (and the name of the target will make it obvious, assume client by default).

A target template is usually one Handlebars template, with any number of partials necessary to make a fully functional tool.

A target generator can be configured with a JSON or YAML file of key-value parameters that can be accessed from the code generation templates.

Each target’s entry point is an index.ts file implementing the Target type.

A conforming implementation consists of at the very least:

OpenAPI specifications tend to have nested objects inside other objects, as is common with all JSON documents. In order to handle this effectively, depending on the placement of the object and whether or not it is anonymously defined (does not appear in the top-level schemas list), a subobject might be generated.

Some languages like Swift or Kotlin will allow nesting a class inside another class definition, however some others do not. In the case where your language does not allow nested classes, it is recommended that you generate these classes at the top level of your generated models, with the nesting generated as part of the name of the class.

For instance, if you have an object Foo, with an anonymous field bar which would ordinarily generate the nested type Bar and be accessed in Kotlin as Foo.Bar, in your flat language you may need to name the type Foo_Bar or some other underutilised delimiter in order to guarantee namespace integrity.

Several targets require some set-up in order to function. Instead of generating entire demo projects, only two things are needed for fully supporting a target and assisting those people who use them:

Each target must handle reserved keywords in a way that would be considered acceptable for a given platform. A general approach is to append an underscore (_) to a variable or class name. Users have the option of providing field and class name overrides in the configuration passed to the generator, so close enough is good enough is the approach taken.

Even if a language supports a special way of accessing keywords, such as Swift’s backtick notation, avoid doing so. It makes actually using the API more painful than it needs to be.

All targets must implement an interceptor pattern for handling the various API key, OAuth and other header and query string mangling operations that affect all endpoints.

The basic principle is that in your language, it should be possible to provide the necessary hooks to modify the headers and query parameters to support authentication and other requirements for a given API.

Where possible, it is considered highly useful to be able to inject a logging interceptor, though with some implementations this may be difficult if not impossible. Try to design your target so that this is achievable.

Targets should—but are not required to—provide a mechanism for handling user-defined formats and parsing them to correct types. This is distinct from actually implementing those formats however. It should be sufficient to provide as part of the service constructors to provide parsing hook functions keyed by the type and format arguments.

In Kotlin, the @Format annotation is used for this purpose and provides a hook. The Gson library can then be provided type handler implementations in the constructor in order to make parsing those formats to the correct data types possible.

Consider for example an object of type string with a format uint64. It is reasonable for this type to therefore be generated to Long and using the @Format("int64") annotation, causing the string to be correctly parsed into the most correct datatype.

openapi-eller supports the direct manipulation of targets using a provided config file.

Some keys are reserved for use by the generator itself (such as fieldRenames) but may be extended with custom keys for use by targets and are accessible within the templates via the config key. Examples of this in use include the ECMAScript target, where different module export styles are used whether or not es6 or commonjs is set to true.

At this stage, configuration is quite rudimentary. There is no support for disjoint values, and no automatically derived variables. This is an area of development going forward, and suggestions are highly welcomed.

Until 1.0.0, this policy does not apply. Experiment at will!

All dependencies must be permissively licensed. Once a target is accepted into the tree, dependencies may not be changed except for minor version changes, except in cases of major bugs. Only in major versions will this requirement be relaxed.