Package "openapi"

Title:	OpenAPI (Swagger) interface
Rating:	Not rated. Create the first rating!
Latest version:	0.8.0
SHA1 sum:	9b002ac4b255e8d95a329790a8a403d16c3cfd1a
Author:	Jan Wielemaker <jan@swi-prolog.org>
Maintainer:	Jan Wielemaker <jan@swi-prolog.org>
Packager:	Jan Wielemaker <jan@swi-prolog.org>
Home page:	https://github.com/JanWielemaker/openapi.git
Download URL:	https://github.com/JanWielemaker/openapi.git

Reviews

No reviews. Create the first review!.

Details by download location

Version	SHA1	#Downloads	URL
0.1	919d4f9fed332e094b394507dfbb6922d5646a16	79	https://github.com/JanWielemaker/openapi.git
0.2	0b42ad9774a76f263298333943ff65848a8580cb	8	https://github.com/JanWielemaker/openapi/archive/V0.2.zip
	76c16b580ad1f21ef92ffa7c695b398c7b801ec0	29	https://github.com/JanWielemaker/openapi.git
	cc0a1423f82ddf203f6f3a15f95c0abeb18cc56b	3	https://github.com/JanWielemaker/openapi.git
	eef2c2e44f561b47e2c88f9da4452430b8190457	1	https://github.com/JanWielemaker/openapi.git
0.2.1	3644009802c941f30e20cfb84f2e776226bc9a3b	6	https://github.com/JanWielemaker/openapi/archive/V0.2.1.zip
	3ffac2636dd784c03a85913eaeae97c74bfdf35d	1	https://github.com/JanWielemaker/openapi.git
	e104d81ca9c67940931e3b88e83c0b2fe18f619d	2	https://github.com/JanWielemaker/openapi.git
0.7.0	52bb2e06770402ff9a894b568980a7135db2e8bb	1	https://github.com/JanWielemaker/openapi.git
0.7.1	3337f74f0e4aba7be81c76b830305a26fbf3273e	2	https://github.com/JanWielemaker/openapi.git
0.8.0	9b002ac4b255e8d95a329790a8a403d16c3cfd1a	3	https://github.com/JanWielemaker/openapi.git

SWI-Prolog OpenAPI (Swagger) interface

Design

There are two options to support OpenAPI:

1. Use an OpenAPI file as a specification for the interface, only providing the body implementation in Prolog.
2. Specify the API in Prolog and generate an OpenAPI document for it.

This library implements the first option. Future versions may reuse a lot of the infrastructure to implement the second option.

Components

The single library(openapi) implements the following components:

1. A compiler that creates a Prolog friendly representation of the operations described in the OpenAPI file.
2. An HTTP request dispatcher that uses the above to
   • Find the operation
   • Extract the parameters (from headers, path, query and request body)
   • Check the argument types
   • Call the (user defined) implementation
   • Check the response type
   • Return the reply document
3. A compiler that creates the client predicates as wrappers around http_open/3. The wrapper does
   • Type-check the parameters
   • Use the parameters to populate the request header, formulate the URL and optional request body for http_open/3.
   • Run the request
   • Type-check and return the returned answer.

In addition, there is a SWI-Prolog app script openapi that wraps the above library to create the skeleton server and client, including PlDoc comments for the operations.

Using this package

First of all, obtain an OpenAPI file using OpenAPI version 3. Now, to generate a server, do

swipl openapi --server=server.pl spec.yaml

This creates a Prolog file server.pl with documented predicate skeletons that must be filled by you. We advice to write the actual implementation of the server in a separate module such that the implementation you have to add to this file is short. This makes upgrading and deploying multiple versions of the server API much easier. There are additional options:

• `--httpd` includes an HTTP server in server.pl. For more complicated projects you probably want something more advanced. This quickly gets you started though.
• `--ui` includes the swagger ui, so you can interactively explore the API in your browser.

To generate a client run

swipl openapi --client=client.pl spec.yaml

This creates documented predicates that call the API. The server address is extracted from spec.yaml. Using the option `--module`, the client file is created as a Prolog module that exports the API.

The predicate mapping

The operationId from the OpenAPI file is used as the name of the predicate, both for the server and client. The arguments are extracted from the parameters specification in the OpenAPI file. Required arguments use a normal Prolog argument. Optional parameters are passed using a Prolog option list. If there is a return value, this is positioned after the required argument and before the option list. On the client side, normal responses are returned as data. The default is mapped to an exception of the form error(rest_error(Code, Data),_), where Code is the HTTP status code and Data the data returned by the server. If an operation only defines code 204 (no content) and a default, the parameter is missing in the client and the predicate succeeds if the server replies 204 or throws an exception as above otherwise.

Server reply

The implementation skeleton for each server operation has a variable Response. The implementation must succeed and bind Response to one of the terms below.

• status(Code)
• status(Code, Data)

Currently, Data must be a term suitable for json_write_dict/3. Future versions will support a other replies and a hook to extend the reply types.

Examples

See the examples directory for two examples from the Swagger site.

Prerequisites

SWI-Prolog 9.2/9.3.

Contents of pack "openapi"

Pack contains 16 files holding a total of 131K bytes.