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.
- For creating client stub code, cl-mustache which is template renderer is used.
- For HTTP communication, drakma which is HTTP client in common lisp is used.
- For JSON, cl-json which is JSON encodrer/decoder is used.
cl-swagger-codegen can be installed by quicklisp.
- Download source code
https://github.com/incjung/cl-swagger-codegen.git
- Load/build in REPL session
(asdf:load-system "cl-swagger")
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/
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")
(generate-client "http://petstore.swagger.io/v2/swagger.json" #p"./example/pet-api-client.lisp")
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\"}"
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.
(generate-client #p"./example/urlshortener.json" #p"./example/urlshortener-api-client.lisp")
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"
To acquire and use your API key, visit "https://developers.google.com/url-shortener/v1/getting_started" and get API key
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.
(generate-client #p"./example/cal-swagger.json" #p"./example/cal-api-client.lisp")
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.
When the rest api require basic authorization, you can use. :basic-authorization
(<function-Name> :basic-authorization '("id" . "password"))
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)
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"
}