openapi

From Lazarus wiki
Jump to navigationJump to search

Overview

FPC has support for reading and writing OpenAPI documents, as well as generating pascal code from an OpenAPI document.

Available units

All units are in the packages/fcl-openapi/src subdirectory of the FPC source tree.

fpopenapi.types
contains many enumerated types. Members in all OpenAPI classes are implemented as properties, and the properties are created on the fly in their getter.
To know whether a certain property was read from the description or not, all classes have a HasKeyWord function which accepts an enumerated (there is a value for each
possible member) and returns True if the property was read from file.
fpopenapi.objects
This unit contains the classes that describe the OpenAPI document: for every OpenAPI construct, a class exists. The openAPI document is described by
the TOpenAPI class, the path items are described using TPathItem, an operation using TAPIOperation and so on.
The code completion of Lazarus will help you navigate through all classes.
fpopenapi.reader
This unit contains a reader for an OpenAPI description (in JSON format, YAML is not supported at the moment).

It will read the file and populate all classes from the fpopenapi.objects unit as needed.

fpopenapi.writer
This unit contains a class that writes out a TOpenAPI instance as JSON.
fpopenapi.pascaltypes
Similar to the fpjson.schema.pascaltypes unit,
this unit contains classes that describe the services (class TAPIservice} and methods (class TAPIServiceMethod) from the OpenAPI description.
All service definitions are contained in a TAPIData class.
fpopenapi.generators
In this unit you'll find all classes that write out the services (class TAPIservice} and methods (class TAPIServiceMethod) as pascal objects.
fpopenapi.codegen
this unit contains a class that will create and use all the classes to write all needed units to create a service client and/or server.

Available tools

The openapi2pas tool (available in the utils/openapi directory) will take an OpenAPI description file and output 2 to 6 units, depending on the chosen options. It supports the following command-line options:

-a --async
Generate asynchronous service calls.
-b --abstract
Split server in abstract handler and implementation modules (and units). This is only useful in combination with the -r option.
-c --client
Generate client-side service interface an proxy implementaton.
-C --config=FILE
Read config file with converter settings.
-d --delphi
Generate delphi code for DTO/Serializer/Service definitions.
-e --enumerated
Use enumerateds (default is to keep strings).
-h --help
This message.
-i --input=FILE
OpenAPI JSON File to use. Required.
-n --no-implementation
Skip generation of server service module (only useful when -b is used), use this when you regenerate the service files, but do not wish to override your service description
-o --output=FILE
Base filename for output.
-q --quiet
Be less verbose.
-r --server
Generate a HTTP server module and implementation
-s --service-map=FILE
Read service and method name mapping from file.
-u --uuid-map=FILE
Read (and write) a file with UUIDs for interfaces.
-v --verbose-header
Add OpenAPI description to unit header.
-w --write-config=FILE
Write a configuration file with current settings and exit.

The basic invocation of this tool is:

openapi2pas -i simpleservice.json -o simple

which will produce output like this:

etInfo : a needs serialize: False, deserialize: True
etWarning : No mapping for list: (Tag= ""), Generated: list=SimpleService.list
etInfo : Map list on SimpleService.List
etInfo : Found 1 Dto types
etInfo : Created 1 services
etInfo : Writing Dto definitions to file "simple.Dto.pas"
etInfo : Generating type Ta
etInfo : Writing serialize helpers to file "simple.Serializer.pas"
etInfo : Generating serialization helper type TaSerializer for Dto Ta

It will generate 2 files: simple.Dto.pas, and simple.Serializer.pas

To generate a client, use

openapi2pas -i simpleservice.json -o simple -c

Which will create the Dto and Serializer units, but also 2 other units: simple.Service.Intf.pas and simple.Service.Impl.pas which contain the service definition(s) and proxy implementations.

To generate a server, use

openapi2pas -i simpleservice.json -o simple -r

This will generate a simple.Module.Impl.pas file which contains a complete service, ready for inclusion in fcl-web.

To split the HTTP request handling and actual service calls, use the -b option

openapi2pas -i simpleservice.json -o simple -r -b

This will generate a simple.Module.Handler.pas file which contains the HTTP handling, and a simple.Module.Impl.pas which just contains the actual service calls.