Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 21 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# cl-openapi
# io.github.cl-sdk.openapi

OpenAPI 3.0 Specification parser for Common Lisp.

`cl-openapi` parses a JSON-encoded OpenAPI 3.0 document into a tree of
`io.github.cl-sdk.openapi` parses a JSON-encoded OpenAPI 3.0 document into a tree of
typed CLOS objects, giving you structured, accessor-based access to every
field defined by the specification.

## Installation

`cl-openapi` is not yet in the Quicklisp distribution. Add it to your
`io.github.cl-sdk.openapi` is not yet in the Quicklisp distribution. Add it to your
project with [qlot](https://github.com/fukamachi/qlot):

```
Expand All @@ -19,54 +19,54 @@ github cl-openapi cl-sdk/cl-openapi :branch main
Then run `qlot install` and load the system:

```lisp
(ql:quickload :cl-openapi)
(ql:quickload :io.github.cl-sdk.openapi)
```

## Usage

### Parsing a document

The single public entry point is `cl-openapi:parse`. It accepts a JSON
The single public entry point is `io.github.cl-sdk.openapi:parse`. It accepts a JSON
string, a character stream, or a binary (octet) stream and returns an
`openapi-document` instance.

```lisp
;; From a string
(defvar *doc*
(cl-openapi:parse
(io.github.cl-sdk.openapi:parse
"{\"openapi\":\"3.0.0\",
\"info\":{\"title\":\"Pet Store\",\"version\":\"1.0.0\"},
\"paths\":{}}"))

;; From a file
(with-open-file (stream "/path/to/openapi.json")
(defvar *doc* (cl-openapi:parse stream)))
(defvar *doc* (io.github.cl-sdk.openapi:parse stream)))
```

### Accessing fields

Every field is exposed through a typed accessor named `<class>-<field>`:

```lisp
(cl-openapi:openapi-version *doc*) ; => "3.0.0"
(io.github.cl-sdk.openapi:openapi-version *doc*) ; => "3.0.0"

(let ((info (cl-openapi:openapi-info *doc*)))
(cl-openapi:info-title info) ; => "Pet Store"
(cl-openapi:info-version info)) ; => "1.0.0"
(let ((info (io.github.cl-sdk.openapi:openapi-info *doc*)))
(io.github.cl-sdk.openapi:info-title info) ; => "Pet Store"
(io.github.cl-sdk.openapi:info-version info)) ; => "1.0.0"

;; Paths is a hash-table keyed by path string
(let ((item (gethash "/pets" (cl-openapi:openapi-paths *doc*))))
(cl-openapi:operation-id
(cl-openapi:path-item-get item))) ; => "listPets"
(let ((item (gethash "/pets" (io.github.cl-sdk.openapi:openapi-paths *doc*))))
(io.github.cl-sdk.openapi:operation-id
(io.github.cl-sdk.openapi:path-item-get item))) ; => "listPets"
```

Optional fields that are absent from the source document are left **unbound**
on their slot. Use `slot-boundp` to test for presence before accessing them.

```lisp
(let ((info (cl-openapi:openapi-info *doc*)))
(when (slot-boundp info 'cl-openapi::description)
(cl-openapi:info-description info)))
(let ((info (io.github.cl-sdk.openapi:openapi-info *doc*)))
(when (slot-boundp info 'io.github.cl-sdk.openapi::description)
(io.github.cl-sdk.openapi:info-description info)))
```

### `$ref` handling
Expand All @@ -76,10 +76,10 @@ either the concrete typed object or a `reference` instance whose single
accessor is `reference-ref` (the raw `$ref` string).

```lisp
(let ((param (aref (cl-openapi:operation-parameters op) 0)))
(if (typep param 'cl-openapi:reference)
(cl-openapi:reference-ref param) ; => "#/components/parameters/Limit"
(cl-openapi:parameter-name param))) ; => "limit"
(let ((param (aref (io.github.cl-sdk.openapi:operation-parameters op) 0)))
(if (typep param 'io.github.cl-sdk.openapi:reference)
(io.github.cl-sdk.openapi:reference-ref param) ; => "#/components/parameters/Limit"
(io.github.cl-sdk.openapi:parameter-name param))) ; => "limit"
```

## API Reference
Expand Down
4 changes: 2 additions & 2 deletions decode.lisp
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
(in-package #:cl-openapi)
(in-package #:io.github.cl-sdk.openapi)

;;; JSON decoding for OpenAPI objects.
;;;
Expand Down Expand Up @@ -573,5 +573,5 @@ INPUT may be a JSON string, a character stream, or a binary (octet) stream.
Binary streams are decoded as UTF-8 via flexi-streams (delegated to cl-json).

Example:
(cl-openapi:parse \"{\\\"openapi\\\":\\\"3.0.0\\\",\\\"info\\\":{...},...}\")"
(io.github.cl-sdk.openapi:parse \"{\\\"openapi\\\":\\\"3.0.0\\\",\\\"info\\\":{...},...}\")"
(json:decode-json 'openapi-document (json:parse input)))
2 changes: 1 addition & 1 deletion cl-openapi.asd → io.github.cl-sdk.openapi.asd
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
(asdf:defsystem #:cl-openapi
(asdf:defsystem #:io.github.cl-sdk.openapi
:description "Open API Specification for Common Lisp."
:license "Unlicense"
:version "0.0.1"
Expand Down
6 changes: 3 additions & 3 deletions cl-openapi.test.asd → io.github.cl-sdk.openapi.test.asd
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
(asdf:defsystem #:cl-openapi.test
:description "FiveAM test suite for cl-openapi."
(asdf:defsystem #:io.github.cl-sdk.openapi.test
:description "FiveAM test suite for io.github.cl-sdk.openapi."
:license "Unlicense"
:version "0.0.1"
:depends-on (#:fiveam
#:cl-openapi)
#:io.github.cl-sdk.openapi)
:pathname "t"
:serial t
:components ((:file "package")
Expand Down
4 changes: 2 additions & 2 deletions package.lisp
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
(defpackage #:cl-openapi
(defpackage #:io.github.cl-sdk.openapi
(:use #:cl)
(:export
;; Top-level entry point
Expand Down Expand Up @@ -256,4 +256,4 @@
#:reference
#:reference-ref))

(in-package :cl-openapi)
(in-package :io.github.cl-sdk.openapi)
Loading
Loading