From 1354ec43d848c6b26bd60b280b7dcc3252850d0b Mon Sep 17 00:00:00 2001 From: Colin Okay Date: Sat, 12 Feb 2022 13:54:56 -0600 Subject: updating documentation generation --- example/lazybones-test.lisp | 71 +++++++++++++++++++++----------------------- lazybones-documentation.lisp | 17 +++++++---- 2 files changed, 46 insertions(+), 42 deletions(-) diff --git a/example/lazybones-test.lisp b/example/lazybones-test.lisp index be50fc8..3c04065 100644 --- a/example/lazybones-test.lisp +++ b/example/lazybones-test.lisp @@ -10,12 +10,13 @@ (in-package :lazybones-test) -;; first make a server and add some custom error responses + +;; First make a server and add some custom error responses (defvar *server* (lzb:create-server :port 8888)) (defun custom-404 () - (format nil "~a wasn't found :(" (lzb:request-path))) ; can use request functiosn + (format nil "~a wasn't found :o~%" (lzb:request-path))) ; can use request functiosn (defun custom-403 () "You, in particular, can't do that. :P ") @@ -33,7 +34,7 @@ :title "Lazybones Demo App" :version "0.0.0" :description "Just an API that defines some endpoints. These - endpoints aren't meant to accomplish anything. merely to test out + endpoints aren't meant to accomplish anything. Merely testing out the lazybones HTTP routing framework." :content-type "text/plain" ; default content type of server responses. @@ -60,56 +61,52 @@ (http-ok "true")) (defendpoint* :get "/hello/:who:" () () - "Just says hello to WHO" - (http-ok (format nil "Hello ~a" who))) + "Echos back Hello WHO" + (http-ok (format nil "Hello ~a~%" who))) (defendpoint* :post "/hello/:who:" () (:auth t) ; use the default authorizor for the app - "Post something to hello who" + "Echo's back 'Hello WHO, I got your message BODY' where BODY is the post body." (print (lzb:request-header :content-type)) (let ((body (lzb:request-body))) - (http-ok (format nil "Hello ~a, I got your message ~a" + (http-ok (format nil "Hello ~a, I got your message ~a~%" who body)))) -(defendpoint* :get "/search" ((name identity) (age to-int)) () +;; Some helpers, these are used to parse url variables and query +;; parameters. Their docstrings are used in the API documentation + +(defun int (string) + "An Integer" + (parse-integer string)) + +(defun str (string) + "A String" + string) + +(defendpoint* :get "/search" ((name str) (age int)) () "Echo the search parameters in a nice list." (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 - "Echo the search parameters in a nice list, but also has a post-body" - (http-ok - (with-output-to-string (out) - (format out "Query Was:~%~{~a is ~a~%~}~%" - (loop for (x . y) in (lzb:request-parameters) - collect x - collect y)) - (terpri) - (format out "Decoded Post Body: ~s~%" (lzb:request-body))))) - - -(defun to-int (string) - "An Integer" - (parse-integer string)) +(defendpoint* :post "/crapshoot" () (:auth 'crapshoot-authorizer) ; use custom authorizer + "Echos back 'You made it' if the request was authorized" + (http-ok "You made it")) -;; route variables can accept parsers / preformatters +;; Route variables can accept parsers / preformatters ;; 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:" () () - "Echo the search back, but in a specific category" - (assert (typep category 'integer)) ; just to show you. - (http-ok - (format nil "Searching in ~a with parameters:~%~{~a = ~a~%~}~%" - category - (loop for (x . y) in (lzb:request-parameters) - collect x - collect y)))) + +(defendpoint* :get "/random/:lo int:/:hi int:" () () + "Echo back a random number between lo and hi" + (if (< lo hi) + (http-ok + (format nil "The number is: ~a~%" + (+ lo (random (- hi lo))))) + (http-err 404))) ; Can't find a number X such that LO >= HI and LO < X < HI (defun person-by-id (id) - "A Person Instance" + "ID of a person" ;; The real thing might perform some database operation here. If the ;; operation failed, an error could be signalled, in which case a ;; 500 response would be sent to the client. diff --git a/lazybones-documentation.lisp b/lazybones-documentation.lisp index b64ec63..6527f41 100644 --- a/lazybones-documentation.lisp +++ b/lazybones-documentation.lisp @@ -23,7 +23,7 @@ newline (princ "## Endpoints") (dolist (ep (sorted-endpoints endpoints)) - (with-slots (method content-type route authorizer endpoint-documentation) ep + (with-slots (method content-type route authorizer params endpoint-documentation) ep newline (princ "### ") (princ method) (princ " ") (princ (make-route-presentable route)) (terpri) @@ -36,9 +36,16 @@ (dolist (var vars) (princ "- ") (princ var) (a:when-let (val-parser (route-var-value-parser ep var)) - (princ ": ") (princ (strip-newlines (documentation val-parser 'function))))) - newline) - + (princ ": ") (princ (strip-newlines (documentation val-parser 'function)))) + (princ #\newline))) + (when params + newline + (princ "Documented Query Parameters: ") newline + (loop for (var parser) in params + do (princ "- ") (princ (string-downcase (symbol-name var))) + (princ ": ") (princ (strip-newlines (documentation parser 'function))) + (princ #\newline))) + (when authorizer (princ "Authorization Required: ") newline @@ -47,7 +54,7 @@ ((function-or-function-name-p default-authorizer) (princ (ensure-blockquote (documentation default-authorizer 'function))))) newline) - + newline (princ endpoint-documentation) )))))) (defun ensure-blockquote (string) -- cgit v1.2.3