The cl-swagger Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-swagger Reference Manual

This is the cl-swagger Reference Manual, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Apr 08 13:38:09 2019 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

cl-swagger-codegen

Introduction

This project is lisp code generator supporting opened APIs.

A Swagger CodeGen is to build a client easier and consume a Swagger-defined APIs.

We can find a various of codegen for swagger. BUT, WE CAN NOT find any CL generates.

With cl-swagger-codegen, you can generates client stub code of common lisp.

Install/Build

cl-swagger-codegen can be installed by quicklisp.

https://github.com/incjung/cl-swagger-codegen.git
 (asdf:load-system "cl-swagger")

How to generate client Code with cl-swagger

Generating client lisp code from swagger url

Let's take a example.

"http://petstore.swagger.io/" is a sample server Petstore server like "hello world" code. :)

With this page, you can generate a client stub code in current working directory, for example pet-api-client.lisp

(generate-client "http://petstore.swagger.io/v2/swagger.json" #p"./example/pet-api-client.lisp")

Open the pet-api-client.lisp and find a rest-call and pets-pet function:

(defun rest-call (....
  "call http-request with basic params and conteent and authorization"
  .....)


... 

(SKIP)

...


;;
;; 
;; * path-url : /pet
;;
(defun post-pet (&key params content basic-authorization)
  (rest-call "http://petstore.swagger.io/v2" "/pet" :params params :content content
                            :basic-authorization basic-authorization
                            :method :post
                            :accept "application/json"
                            :content-type "application/json"))
                            
(SKIP)

rest-call is core function for HTTP communication. This function will always be created by cl-swagger-gen. The rest funtions are wrapping the rest-call for convenience.

A post-pet is a wrapper function to access POST /PET/

Generating client lisp code directly from swagger json file

Without running server providing a swagger JSON url, you can create a client code from swagger JSON FILE. Assuming you have a swagger file, for example, swagger.json, you can generate a client code.

(generate-client #p"./directory-path/swagger.json" "client2.lisp")

How to use the client code that are created by cl-swagger

Example 1: Petstore

Create Client Code

(generate-client "http://petstore.swagger.io/v2/swagger.json" #p"./example/pet-api-client.lisp")

Useage

Find the pet-api-client.lisp and load the file.

To add new pet to the online store, use POST-PET. We are using cl-json (https://common-lisp.net/project/cl-json/) to edit json structure.

(post-pet 
 :content (cl-json:encode-json-to-string '((id . 0)
                                           (:category . ((:id . 0) (:name . "string")))
                                           (:name . "doggie")
                                           ("photoUrls" . #("string"))
                                           (:tags . (((:id . 0)
                                                      (:name . "string"))))
                                           (:status . "available"))))

This is same with curl command:

curl -X POST "http://petstore.swagger.io/v2/pet" -H "accept: application/xml" -H "Content-Type: application/json" -d "{ \"id\": 0, \"category\": { \"id\": 0, \"name\": \"string\" }, \"name\": \"doggie\", \"photoUrls\": [ \"string\" ], \"tags\": [ { \"id\": 0, \"name\": \"string\" } ], \"status\": \"available\"}"

Example 2: Google URLShortener Service

Please visit the api explorer (https://developers.google.com/apis-explorer/#p/urlshortener/v1/).

For swagger file, you can find open-api swagger at https://github.com/APIs-guru/openapi-directory/tree/master/APIs/googleapis.com. Inthe case that the swagger is not a json format, I just used https://www.browserling.com/tools/yaml-to-json to save the swagger.json.

Create Client Code

(generate-client #p"./example/urlshortener.json" #p"./example/urlshortener-api-client.lisp")

Useage

Find the urlshortener-api-client.lisp and load the file.

To expand a shortened URL, find get-url.

(get-url :params '(("key" . "XXXXX-YOUR-KEY-XXXXXXXXXXXX")
                   ("shortUrl" . "https://goo.gl/fbsS")))

This is same with curl command:

;;  curl -X GET "https://www.googleapis.com/urlshortener/v1/url?shortUrl=https%3A%2F%2Fgoo.gl%2FfbsS&key=XXXXXXX" -H "accept: application/json"

API KEY

To acquire and use your API key, visit "https://developers.google.com/url-shortener/v1/getting_started" and get API key

Example 3: Google Calendar Service

Please visit the api explor (https://developers.google.com/apis-explorer/#p/calendar/v3/)

For swagger file, you can find open-api swagger at https://github.com/APIs-guru/openapi-directory/tree/master/APIs/googleapis.com. In the case that the swagger is not a json format, I just used https://www.browserling.com/tools/yaml-to-json to save the swagger.json.

Create Client Code

(generate-client #p"./example/cal-swagger.json" #p"./example/cal-api-client.lisp")

Useage

Find the cal-api-client.lisp and load the file.

To get my scheduler calendars, use get-users-me-calendarlist function.

(get-users-me-calendarlist :params `(("access_token" . ,access-token)))

access_token came from Google Oauth2 process. You shoud have google account for Google services if you want to get your token.

Misc

BASIC AUTHORIZATON

When the rest api require basic authorization, you can use. :basic-authorization

(<function-Name> :basic-authorization '("id" . "password"))

OAUTH2 AUTHORIZATON

For OAuth2, use access-token with :params

(<function-Name> :params '(("access-token" "-your-key-")))

ex)

(defparameter access-token "XXXXXXX YOUR-TOKEN-KEN XXXXXXXX")

(get-users-me-calendarlist :params `(("access_token" . ,access-token)))

For more information and exaple, please read my [wiki] (https://github.com/incjung/cl-swagger-codegen/wiki/Google-Oauth2-Process)

JSON Structure

For json object, cl-swagger-codegen uses cl-json.

(cl-json:encode-json-to-string '((id . 0)
                                (:category . ((:id . 0) (:name . "string")))
                                (:name . "doggie")
                                ("photoUrls" . #("string"))
                                (:tags . (((:id . 0)
                                (:name . "string"))))
                                (:status . "available")))

for json object:

{
  "id": 0,
  "category": {
    "id": 0,
    "name": "string"
  },
  "name": "doggie",
  "photoUrls": [
    "string"
  ],
  "tags": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "status": "available"
}

Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-swagger

Author

Inchul <ijung@mapr.com>

License

BSD

Description

code generatter for swagger

Dependencies
Source

cl-swagger.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-swagger.asd

Location

cl-swagger.asd

Systems

cl-swagger (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-swagger/package.lisp

Parent

cl-swagger (system)

Location

package.lisp

Packages

cl-swagger


Previous: , Up: Lisp files   [Contents][Index]

3.1.3 cl-swagger/code-gen.lisp

Dependency

package.lisp (file)

Parent

cl-swagger (system)

Location

code-gen.lisp

Exported Definitions

generate-client (function)

Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cl-swagger

Source

package.lisp (file)

Use List
Exported Definitions

generate-client (function)

Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Functions

Function: generate-client URL FILEPATH &optional ACCEPT ACCEPT-TYPE

exposing function for client code generater

Package

cl-swagger

Source

code-gen.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *parameter-pattern*
Package

cl-swagger

Source

code-gen.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: convert-json-templete &optional CONTEXT OUTPUT-STREAM
Package

cl-swagger

Source

/home/quickref/quicklisp/dists/quicklisp/software/cl-mustache-20150923-git/mustache.lisp

Function: fetch-json THIS-URL

gets JSON with this URL only when response-code is 200

Package

cl-swagger

Source

code-gen.lisp (file)

Function: generate-client-with-json JSON FILEPATH &optional ACCEPT ACCEPT-TYPE

generater a lisp code with swagger-json

Package

cl-swagger

Source

code-gen.lisp (file)

Function: get-basepath JSON

gets base-path

Package

cl-swagger

Source

code-gen.lisp (file)

Function: get-host JSON

gets hostname

Package

cl-swagger

Source

code-gen.lisp (file)

Function: get-in THIS-ITEMS ALIST

get lists related to this-items

Package

cl-swagger

Source

code-gen.lisp (file)

Function: get-schemes JSON

gets schemes

Package

cl-swagger

Source

code-gen.lisp (file)

Function: make-urls JSON

scheme + hostname + basepath

Package

cl-swagger

Source

code-gen.lisp (file)

Function: normalize-path-name NAME

string –> A-B-C

Package

cl-swagger

Source

code-gen.lisp (file)

Function: normalize-path-url PATH-URL

string –> A/B/C

Package

cl-swagger

Source

code-gen.lisp (file)

Function: parse-path-parameters PATH

returns two values, 1st is non param path element, 2nd are the params. ex) /PARAM1/{PARAM2} ==> (("PARAM1") ("PARAM2"))

Package

cl-swagger

Source

code-gen.lisp (file)

Function: rest-call HOST URL-PATH &key PARAMS CONTENT BASIC-AUTHORIZATION METHOD ACCEPT CONTENT-TYPE

call http-request with basic params and conteent and authorization

Package

cl-swagger

Source

code-gen.lisp (file)

Function: rest-call-function &optional CONTEXT OUTPUT-STREAM
Package

cl-swagger

Source

/home/quickref/quicklisp/dists/quicklisp/software/cl-mustache-20150923-git/mustache.lisp

Function: rest-call-templete-v1 &optional CONTEXT OUTPUT-STREAM
Package

cl-swagger

Source

/home/quickref/quicklisp/dists/quicklisp/software/cl-mustache-20150923-git/mustache.lisp

Function: rest-call-templete-v2 &optional CONTEXT OUTPUT-STREAM
Package

cl-swagger

Source

/home/quickref/quicklisp/dists/quicklisp/software/cl-mustache-20150923-git/mustache.lisp

Function: wrapper-call-templete-v2 &optional CONTEXT OUTPUT-STREAM
Package

cl-swagger

Source

/home/quickref/quicklisp/dists/quicklisp/software/cl-mustache-20150923-git/mustache.lisp


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-swagger.asd: The cl-swagger<dot>asd file
cl-swagger/code-gen.lisp: The cl-swagger/code-gen<dot>lisp file
cl-swagger/package.lisp: The cl-swagger/package<dot>lisp file

F
File, Lisp, cl-swagger.asd: The cl-swagger<dot>asd file
File, Lisp, cl-swagger/code-gen.lisp: The cl-swagger/code-gen<dot>lisp file
File, Lisp, cl-swagger/package.lisp: The cl-swagger/package<dot>lisp file

L
Lisp File, cl-swagger.asd: The cl-swagger<dot>asd file
Lisp File, cl-swagger/code-gen.lisp: The cl-swagger/code-gen<dot>lisp file
Lisp File, cl-swagger/package.lisp: The cl-swagger/package<dot>lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   C   F   G   M   N   P   R   W  
Index Entry  Section

C
convert-json-templete: Internal functions

F
fetch-json: Internal functions
Function, convert-json-templete: Internal functions
Function, fetch-json: Internal functions
Function, generate-client: Exported functions
Function, generate-client-with-json: Internal functions
Function, get-basepath: Internal functions
Function, get-host: Internal functions
Function, get-in: Internal functions
Function, get-schemes: Internal functions
Function, make-urls: Internal functions
Function, normalize-path-name: Internal functions
Function, normalize-path-url: Internal functions
Function, parse-path-parameters: Internal functions
Function, rest-call: Internal functions
Function, rest-call-function: Internal functions
Function, rest-call-templete-v1: Internal functions
Function, rest-call-templete-v2: Internal functions
Function, wrapper-call-templete-v2: Internal functions

G
generate-client: Exported functions
generate-client-with-json: Internal functions
get-basepath: Internal functions
get-host: Internal functions
get-in: Internal functions
get-schemes: Internal functions

M
make-urls: Internal functions

N
normalize-path-name: Internal functions
normalize-path-url: Internal functions

P
parse-path-parameters: Internal functions

R
rest-call: Internal functions
rest-call-function: Internal functions
rest-call-templete-v1: Internal functions
rest-call-templete-v2: Internal functions

W
wrapper-call-templete-v2: Internal functions

Jump to:   C   F   G   M   N   P   R   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*parameter-pattern*: Internal special variables

S
Special Variable, *parameter-pattern*: Internal special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-swagger: The cl-swagger system
cl-swagger: The cl-swagger package

P
Package, cl-swagger: The cl-swagger package

S
System, cl-swagger: The cl-swagger system

Jump to:   C   P   S