Papupata Documentation

Table of contents

Conversion from OpenAPI

Overview

It is not an uncommon need to utilise APIs declared with OpenAPI, or even to implement them. An experimental tool exists for generating papupata API declarations from an OpenAPI 3 document.
This is an experimental tool, its functionality is lacking and they way it is used might still change!

Table of contents

Getting Started

The tool is provided as a package called "papupata-from-openapi". You can install it into your repository if you want more control over the version of it being used, or you can run it directly with npx.

Examples

npm install papupata-from-openapi
npx papupata-from-openapi
For programmatic usage, installing it is of course the way to go.

Command-line

npx papupata-from-openapi
npx papupata-from-openapi [--config=<configfile>]
npx papupata-from-openapi <openapi> [<output>] [--exportName=<name>]

Parameters

NameTypeDescription
configfilenameIf given, the referenced file is used as the config file for papupata-from-openapi. If not given, and there are no other command line parameters a config is searched for from the current directory and its ancestors.
openapifilename/URLReference to an OpenAPI document to convert, either as a filename or an URL. Has no effect when config file is used.
outputfilenameThe filename where the converted API declaration is to be stored. If omitted, it is printed to standard output. Has no effect when config file is used.
exportNamestringThe name used for the export of API declarations in the generated file. Has no effect when config file is used.

Configuration

Configuration can be done using either command-line parameters, or using a config file. You can specify a config file using the command-line parameter --config. If you do not, and the command line does not indicate a conversion, a config file is automatically searched for.

The search starts from the current directory, and goes towards the root directory until it finds a configuration file, or concludes that it cannot.

The configuration file can be called either .papupata-from-openapi.js or .papupata-from-openapi.json. A .js file should be valid javascript the current version of node can execute, and it should export the configuration itself. The JSON file should just contain the configuration.

The configuration itself should be an array of all the conversions that are to take place.

[
  {
    "openapiLocation": "https://example.com/openapi.yaml",
    "outputTo": "./relative/api.ts",
    "exportName": "exampleAPI"
  }
]

Each entry has the following fields:

Parameters

NameTypeDescription
openapiLocationfilename/URLReference to an OpenAPI document to convert, either as a filename or an URL.
outputTofilenameThe filename where the converted API declaration is to be stored. no effect when config file is used.
exportNamestringThe name used for the export of API declarations in the generated file.

All relative paths are resolved relative to the configuration file.

API

At this time no documented API is provided. One will be added in future releases.

Limitations

  • At this time only OpenAPI 3 documents are supported
  • There are no doubt numerous improvements that could be done to the schema-to-typescript conversion
  • Recursive references are not supported