openapi
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.