Did you know ... | Search Documentation: |
Packs (add-ons) for SWI-Prolog |
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 |
No reviews. Create the first review!.
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 | 1 | https://github.com/JanWielemaker/openapi.git |
There are two options to support OpenAPI:
This library implements the first option. Future versions may reuse a lot of the infrastructure to implement the second option.
The single library(openapi)
implements the following components:
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.
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:
server.pl
. For more
complicated projects you probably want something more advanced.
This quickly gets you started though.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 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.
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.
See the examples
directory for two examples from the Swagger site.
SWI-Prolog 9.2/9.3.
Pack contains 16 files holding a total of 131K bytes.