From be0d066f5dbdb9235304928a1927c1200375c9c1 Mon Sep 17 00:00:00 2001 From: Joel Kaasinen Date: Wed, 19 Apr 2023 11:03:15 +0300 Subject: [PATCH] doc: document OpenAPI3 multiple examples --- doc/ring/openapi.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/doc/ring/openapi.md b/doc/ring/openapi.md index d3e127cf..c5187095 100644 --- a/doc/ring/openapi.md +++ b/doc/ring/openapi.md @@ -31,6 +31,29 @@ Coercion keys also contribute to the docs: Use `:request` parameter coercion (instead of `:body`) to unlock per-content-type coercions. See [Coercion](coercion.md). +## Custom OpenAPI data + +The `:openapi` route data key can be used to add top-level or +route-level information to the generated OpenAPI spec. This is useful +for providing `"securitySchemes"`, `"examples"` or other OpenAPI keys +that are not generated automatically by reitit. + +```clj +["/foo" + {:post {:parameters {:body {:name string? :age int?}} + :openapi {:requestBody + {:content + {"application/json" + {:examples {"Pyry" {:summary "Pyry, 45y" + :value {:name "Pyry" :age 45}} + "Cat" {:summary "Cat, 8y" + :value {:name "Cat" :age 8}}}}}}} + ...}}] +``` + +See [the http-swagger example](../../examples/http-swagger) for a +working examples of `"securitySchemes"` and `"examples"`. + ## OpenAPI spec Serving the OpenAPI specification is handled by `reitit.openapi/create-openapi-handler`. It takes no arguments and returns a ring handler which collects at request-time data from all routes and returns an OpenAPI specification as Clojure data, to be encoded by a response formatter.