From 61c1d08633d9b1391c00f5fe1716bd915a793b8d Mon Sep 17 00:00:00 2001 From: Colin Okay Date: Sat, 12 Feb 2022 13:23:13 -0600 Subject: updated readme and example --- README.md | 51 ++++++++++++++------------------------------- example/lazybones-test.lisp | 26 +++++++++++------------ 2 files changed, 29 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 4299384..5d85070 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ See the example below for more. (in-package :hello-lazybones) -(defendpoint* :get "/hello/:name:" () +(defendpoint* :get "/hello/:name:" () () (http-ok (format nil "Welcome to Lazybones, ~a" name))) (defvar *my-server* (lzb:create-server)) @@ -106,9 +106,12 @@ The following is quick example showing a few more things that `lazybones` can d (defun custom-403 () "You, in particular, can't do that. :P ") +(defun custom-500 () + "Bah. Error.") + (lzb:set-canned-response *server* 404 'custom-404 "text/plain" ) (lzb:set-canned-response *server* 403 'custom-403 "text/plain" ) -(lzb:set-canned-response *server* 500 #p"/path/to/500error.txt" "text/plain" ) +(lzb:set-canned-response *server* 500 'custom-500 "text/plain") ;; PPROVISION-APP makes an app. You can supply an optional name, a symbol. ;; In lieu of a supplied name, the name of the package is used as the app's name. @@ -134,36 +137,34 @@ The following is quick example showing a few more things that `lazybones` can d ;; app whose name is the current package anme. DEFENDPOINT (without the *) ;; allows you to explictly specify the app where the endpoint is installed. -(defendpoint* :post "/login" () +(defendpoint* :post "/login" () () "Dummy login endpoint for returning a session cookie. Always returns the \"true\" and sends a set-cookie header, setting 'testappsession' to 'coolsessionbro'." - (print (lzb:request-body)) ; dummy implementation prints post body to stdout + (print (lzb:request-body)) ; dummy implementation, prints post body to stdout (setf (lzb:response-cookie "testappsession") "coolsessionbro") (http-ok "true")) -(defendpoint* :get "/hello/:who:" () +(defendpoint* :get "/hello/:who:" () () "Just says hello to WHO" (http-ok (format nil "Hello ~a" who))) -(defendpoint* :post "/hello/:who:" (:auth t) ; use the default authorizor for the app +(defendpoint* :post "/hello/:who:" () (:auth t) ; use the default authorizor for the app "Post something to hello who" + (print (lzb:request-header :content-type)) (let ((body (lzb:request-body))) (http-ok (format nil "Hello ~a, I got your message ~a" who body)))) -(defendpoint* :get "/search" () +(defendpoint* :get "/search" ((name identity) (age to-int)) () "Echo the search parameters in a nice list." - (http-ok (format nil "Query Was:~%~{~a is ~a~%~}~%" - (loop for (x . y) in (lzb:request-parameters) - collect x - collect y)))) + (http-ok (format nil "Name: ~a~%age: ~a~%" name age))) -(defun crapshoot-authorizer () +(defun crapshoot-authorizer () () "Randomly decides that the request is authorized" (< 5 (random 10))) -(defendpoint* :post "/search" (:auth 'crapshoot-authorizer) ; use custom authorizer +(defendpoint* :post "/search" () (:auth 'crapshoot-authorizer) ; use custom authorizer "Echo the search parameters in a nice list, but also has a post-body" (http-ok (with-output-to-string (out) @@ -183,7 +184,7 @@ The following is quick example showing a few more things that `lazybones` can d ;; these will parse a value and supply it to the argument of the handler. ;; int eh following CATEGORY is an int -(defendpoint* :get "/search/:category to-int:" () +(defendpoint* :get "/search/:category to-int:" () () "Echo the search back, but in a specific category" (assert (typep category 'integer)) ; just to show you. (http-ok @@ -200,31 +201,11 @@ The following is quick example showing a few more things that `lazybones` can d ;; 500 response would be sent to the client. (list :name "Colin" :occupation "Macrologist" :id (parse-integer id))) -(defendpoint* :get "/person/:person person-by-id:" (:content-type "application/json") +(defendpoint* :get "/person/:person person-by-id:" () (:content-type "application/json") "Returns a json representation of the person." (http-ok (jonathan:to-json person))) -;; If you like start the server - -(lzb:start-server *server*) - -``` - -## Generate Documentation - -Generate a markdown file documenting the endpoints of an APP / API like so: - -``` - -;; continuing from above -(in-package :lazybones-test) - -(alexandria:write-string-into-file - (lzb:generate-app-documentation (lzb:app)) - #p"lazybones-test-docs.md" - :if-exists :supersede) - ``` Then use your favorite markdown processor to generate HTML or whatever diff --git a/example/lazybones-test.lisp b/example/lazybones-test.lisp index d252849..be50fc8 100644 --- a/example/lazybones-test.lisp +++ b/example/lazybones-test.lisp @@ -20,9 +20,12 @@ (defun custom-403 () "You, in particular, can't do that. :P ") +(defun custom-500 () + "Bah. Error.") + (lzb:set-canned-response *server* 404 'custom-404 "text/plain" ) (lzb:set-canned-response *server* 403 'custom-403 "text/plain" ) -(lzb:set-canned-response *server* 500 #p"/path/to/500error.txt" "text/plain" ) +(lzb:set-canned-response *server* 500 'custom-500 "text/plain") ;; PPROVISION-APP makes an app. You can supply an optional name, a symbol. ;; In lieu of a supplied name, the name of the package is used as the app's name. @@ -48,7 +51,7 @@ ;; app whose name is the current package anme. DEFENDPOINT (without the *) ;; allows you to explictly specify the app where the endpoint is installed. -(defendpoint* :post "/login" () +(defendpoint* :post "/login" () () "Dummy login endpoint for returning a session cookie. Always returns the \"true\" and sends a set-cookie header, setting 'testappsession' to 'coolsessionbro'." @@ -56,29 +59,26 @@ (setf (lzb:response-cookie "testappsession") "coolsessionbro") (http-ok "true")) -(defendpoint* :get "/hello/:who:" () +(defendpoint* :get "/hello/:who:" () () "Just says hello to WHO" (http-ok (format nil "Hello ~a" who))) -(defendpoint* :post "/hello/:who:" (:auth t) ; use the default authorizor for the app +(defendpoint* :post "/hello/:who:" () (:auth t) ; use the default authorizor for the app "Post something to hello who" (print (lzb:request-header :content-type)) (let ((body (lzb:request-body))) (http-ok (format nil "Hello ~a, I got your message ~a" who body)))) -(defendpoint* :get "/search" () +(defendpoint* :get "/search" ((name identity) (age to-int)) () "Echo the search parameters in a nice list." - (http-ok (format nil "Query Was:~%~{~a is ~a~%~}~%" - (loop for (x . y) in (lzb:request-parameters) - collect x - collect y)))) + (http-ok (format nil "Name: ~a~%age: ~a~%" name age))) -(defun crapshoot-authorizer () +(defun crapshoot-authorizer () () "Randomly decides that the request is authorized" (< 5 (random 10))) -(defendpoint* :post "/search" (:auth 'crapshoot-authorizer) ; use custom authorizer +(defendpoint* :post "/search" () (:auth 'crapshoot-authorizer) ; use custom authorizer "Echo the search parameters in a nice list, but also has a post-body" (http-ok (with-output-to-string (out) @@ -98,7 +98,7 @@ ;; these will parse a value and supply it to the argument of the handler. ;; int eh following CATEGORY is an int -(defendpoint* :get "/search/:category to-int:" () +(defendpoint* :get "/search/:category to-int:" () () "Echo the search back, but in a specific category" (assert (typep category 'integer)) ; just to show you. (http-ok @@ -115,7 +115,7 @@ ;; 500 response would be sent to the client. (list :name "Colin" :occupation "Macrologist" :id (parse-integer id))) -(defendpoint* :get "/person/:person person-by-id:" (:content-type "application/json") +(defendpoint* :get "/person/:person person-by-id:" () (:content-type "application/json") "Returns a json representation of the person." (http-ok (jonathan:to-json person))) -- cgit v1.2.3