Generation process

CodeSquared run code generation as three separate phases parse, generate and render.

Parsing and rendering is handled by the framework which lets developers focus purely on specifying the output code they would like to generate.

Parse

To make working with contents of an OpenAPI schema easier, we begin code generation by parsing the schema and converting it to internal objects.

This lets us enrich the objects with additional, useful data. For example, our version of Operation also has API path and method properties added since we refer to them in nearly every use case.

We also add methods to look up references at runtime and simplify common operations such as getting the parameters of an API operation.

We group API schema contents into two object categories: operations which represent API operations and models which are data type schemas defined as references that have their own name.

Generate

During the generate process, CodeSquared uses developer provided generators to convert operations and models into Files.

This is where CodeSquared stands out from other code generators. Rather than only generating a single set of pre-defined outputs, Sktmc lets developers specify the code they want to output using TypeScript packages called generators.

Generators can be one of two types operations and models.

Operation generators

Operation generators convert operation objects into code which interacts with that particular API operation. For example, one generator could be responsible for generating forms that submit data to POST or PUT api endpoints.

Model generators

Model generators are more specialised and are used to convert JSON schema type defintions to type definitions you can use in your code. For example, tt can be TypeScript types or a type defined by a third party library such as Zod.

Stringable

When code is generated it is represented as a Stringable object. It is any object with a custom toString() method which when called returns a string representation of the object. We use this toString() method where we define how a piece of data gets converted to corresponding code.

Files

To make generated code usable, CodeSquared combines each Stringable value with an Identifier to create a Definition.

Dependency handling

Often the artifacts produced by one generator depend on artifacts produced by another generator. In these cases CodeSquared will prioritise generation of the dependency if it is not already created and reuse them