Codegeneration from OAS3

Actual Roadmap is published!

This project is a kit of tools for code generation from OpenAPI3 specification:

• Data types and models (see generated examples from this spec)
• REST API client services (examples)
• Validation tools in clients
• Extracted JSON Schemas (example)

In the future it can be appended with:

• REST API backend service templates
• Pure validation tools and validation presets

Some features:

Features of data type generation:

• Can deal with recursive dependencies and deep nestings
• Smart adding of comments for different contexts (types / properties / type variants / interface concatenation parts )
• Extracts common types and adds imports where it is necessary
• Makes correct arrays of simple and complex types
• Marks optional parameters of objects if they are not in required
• Understands where has to use OOP inheritance and interface concatenation
• Converts JSON Schema enums to simple type definitions or in TypeScript Enum, if it uses $ref to component
• Converts additionalProperties to correct typescript constructions
• Converts anyOf / allOf to type variants
• Makes complex data types of
  • responses with few codes
  • requests
  • parameters (both in a query and in a search)

Table of contents

1. Demo
2. Packages
3. How to use
   • oapi3ts-cli: using in NodeJS scripts
   • CLI arguments for oapi3ts-cli
   • oapi3ts API
4. Work with this project

Demo

• TypeScript types and Angular client services in a demo project
• Stackblitz playground
• Example of using of generated data types in a demo backend-controller
• Example of using of generated data types in a demo frontend application
• todo-app-backend — demo backend application (NestJS) uses @codegena tools
• todo-app — demo frontend application (Angular) uses @codegena tools
• Source code of codegena-playground. Demonstrates work in a browser.

Packages

• oapi3ts — core library with base adadpters for supported languages. Does generation of data types and models.
• ng-api-service — experimental library for generating Angular client services
• oapi3ts-cli — Aggregator for supported generation libraries. Provides application working in browser or in CLI.
• todo-app-scheme — Demo library with auto generated data types and Angular services. Works locally, does't get published in NPM.

How to use

oapi3ts-cli: using in NodeJS scripts

Install:

npm i @codegena/oapi3ts-cli

or

yarn add @codegena/oapi3ts-cli

So you can use @codegena/oapi3ts-cli in NodeJS scripts. For example, lets create update-typings.js script with code:

"use strict";

var cliLib = require('@codegena/oapi3ts-cli');
var cliApp = new cliLib.CliApplication;

cliApp.createTypings();
cliApp.createServices('angular');

Then launch:

node ./update-typings.js --srcPath ./specs/todo-app-spec.json --destPath ./ --separatedFiles true

Class CliApplication will get command line arguments destPath, srcPath and separatedFiles by itself.

CLI arguments for oapi3ts-cli

Also, you can set some of options for convertor's configuration config via CLI:

oapi3ts API

You can use API of @codegena/oapi3ts to convert whole OAS3 schema object to data type descriptions. Example for TypeScript:

import { Convertor } from '@codegena/oapi3ts';

const convertor: Convertor = new Convertor();
const context = {};

/**
 * Base models of specification:
 *  - Requests bodies models
 *  - Requests params sets models
 *  - Responses models
 *
 * Converting starts from entry points and extracts
 * referred types and dependencies. It s why we need
 * to get "entry points". 
 */
const entryPoints = convertor.getOAPI3EntryPoints(context);

/**
 * Rendering each type: every entry point and each of
 * theirs related types.
 */
Convertor.renderRecursive(
    entryPoints,
    (descriptor: DataTypeDescriptor, text) => {
        // Here your code: you get text and type descriptor.
        // Example of using: 
        // https://github.com/koshevy/codegena/blob/master/libs/oapi3ts-cli/src/abstract-application.ts#L57
    }
);

And also, you can convert just a JSON-schema into type descriptor and render it:

import { Convertor } from 'oapi3codegen';
// you need prettier to beautify result of rendering
import * as prettier from 'prettier';
// provides `_.each(...)` for our example
import * as _ from 'lodash';

const convertor: Convertor = new Convertor();

const anotherJsonSchemaObject = {
    "title": "Person",
    "description": "Information about person you have to register in your system.",
    "type": "object",
    "properties": {
        "firstName": {
            "type": "string"
        },
        "lastName": {
            "type": "string"
        },
        "age": {
            "description": "Age in years",
            "type": "integer",
            "minimum": 0
        }
    },
    "required": ["firstName", "lastName"]
};

const convertResult = convertor.convert(
    anotherJsonSchemaObject,
    {},
    'AnotherType'
);

_.each(convertResult, typeDescriptor => {
    const typeCode = prettier.format(
        typeDescriptor.render([]),
        {parser: 'typescript'}
    );

    console.log(typeCode);
});

It will output:

/**
 * ## Person
 * Information about person you have to register in your system.
 */
export interface AnotherType {
  firstName: string;

  lastName: string;

  /**
   * Age in years
   */
  age?: number;
}

Work with this project