mirror of
https://github.com/metosin/reitit.git
synced 2025-12-20 17:41:11 +00:00
1145 lines
45 KiB
HTML
1145 lines
45 KiB
HTML
|
|
<!DOCTYPE HTML>
|
|
<html lang="" >
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
|
|
<title>Swagger Support · GitBook</title>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
|
|
<meta name="description" content="">
|
|
<meta name="generator" content="GitBook 3.2.3">
|
|
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="../gitbook/style.css">
|
|
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="../gitbook/gitbook-plugin-hints/plugin-hints.css">
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="../gitbook/gitbook-plugin-highlight/website.css">
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="../gitbook/gitbook-plugin-search/search.css">
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="../gitbook/gitbook-plugin-fontsettings/website.css">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<meta name="HandheldFriendly" content="true"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
|
|
<meta name="apple-mobile-web-app-capable" content="yes">
|
|
<meta name="apple-mobile-web-app-status-bar-style" content="black">
|
|
<link rel="apple-touch-icon-precomposed" sizes="152x152" href="../gitbook/images/apple-touch-icon-precomposed-152.png">
|
|
<link rel="shortcut icon" href="../gitbook/images/favicon.ico" type="image/x-icon">
|
|
|
|
|
|
<link rel="next" href="RESTful_form_methods.html" />
|
|
|
|
|
|
<link rel="prev" href="compiling_middleware.html" />
|
|
|
|
|
|
</head>
|
|
<body>
|
|
|
|
<div class="book">
|
|
<div class="book-summary">
|
|
|
|
|
|
<div id="book-search-input" role="search">
|
|
<input type="text" placeholder="Type to search" />
|
|
</div>
|
|
|
|
|
|
<nav role="navigation">
|
|
|
|
|
|
|
|
<ul class="summary">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="header">Introduction</li>
|
|
|
|
|
|
|
|
<li class="chapter " data-level="1.1" data-path="../">
|
|
|
|
<a href="../">
|
|
|
|
|
|
Introduction
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
<li class="header">Basics</li>
|
|
|
|
|
|
|
|
<li class="chapter " data-level="2.1" data-path="../basics/route_syntax.html">
|
|
|
|
<a href="../basics/route_syntax.html">
|
|
|
|
|
|
Route Syntax
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="2.2" data-path="../basics/router.html">
|
|
|
|
<a href="../basics/router.html">
|
|
|
|
|
|
Router
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="2.3" data-path="../basics/path_based_routing.html">
|
|
|
|
<a href="../basics/path_based_routing.html">
|
|
|
|
|
|
Path-based Routing
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="2.4" data-path="../basics/name_based_routing.html">
|
|
|
|
<a href="../basics/name_based_routing.html">
|
|
|
|
|
|
Name-based Routing
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="2.5" data-path="../basics/route_data.html">
|
|
|
|
<a href="../basics/route_data.html">
|
|
|
|
|
|
Route Data
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="2.6" data-path="../basics/route_data_validation.html">
|
|
|
|
<a href="../basics/route_data_validation.html">
|
|
|
|
|
|
Route Data Validation
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="2.7" data-path="../basics/route_conflicts.html">
|
|
|
|
<a href="../basics/route_conflicts.html">
|
|
|
|
|
|
Route Conflicts
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
<li class="header">Coercion</li>
|
|
|
|
|
|
|
|
<li class="chapter " data-level="3.1" data-path="../coercion/coercion.html">
|
|
|
|
<a href="../coercion/coercion.html">
|
|
|
|
|
|
Coercion Explained
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="3.2" data-path="../coercion/schema_coercion.html">
|
|
|
|
<a href="../coercion/schema_coercion.html">
|
|
|
|
|
|
Plumatic Schema
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="3.3" data-path="../coercion/clojure_spec_coercion.html">
|
|
|
|
<a href="../coercion/clojure_spec_coercion.html">
|
|
|
|
|
|
Clojure.spec
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="3.4" data-path="../coercion/data_spec_coercion.html">
|
|
|
|
<a href="../coercion/data_spec_coercion.html">
|
|
|
|
|
|
Data-specs
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
<li class="header">Ring</li>
|
|
|
|
|
|
|
|
<li class="chapter " data-level="4.1" data-path="ring.html">
|
|
|
|
<a href="ring.html">
|
|
|
|
|
|
Ring-router
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="4.2" data-path="reverse_routing.html">
|
|
|
|
<a href="reverse_routing.html">
|
|
|
|
|
|
Reverse-routing
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="4.3" data-path="default_handler.html">
|
|
|
|
<a href="default_handler.html">
|
|
|
|
|
|
Default handler
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="4.4" data-path="slash_handler.html">
|
|
|
|
<a href="slash_handler.html">
|
|
|
|
|
|
Slash handler
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="4.5" data-path="static.html">
|
|
|
|
<a href="static.html">
|
|
|
|
|
|
Static Resources
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="4.6" data-path="dynamic_extensions.html">
|
|
|
|
<a href="dynamic_extensions.html">
|
|
|
|
|
|
Dynamic Extensions
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="4.7" data-path="data_driven_middleware.html">
|
|
|
|
<a href="data_driven_middleware.html">
|
|
|
|
|
|
Data-driven Middleware
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="4.8" data-path="transforming_middleware_chain.html">
|
|
|
|
<a href="transforming_middleware_chain.html">
|
|
|
|
|
|
Transforming Middleware Chain
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="4.9" data-path="middleware_registry.html">
|
|
|
|
<a href="middleware_registry.html">
|
|
|
|
|
|
Middleware Registry
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="4.10" data-path="default_middleware.html">
|
|
|
|
<a href="default_middleware.html">
|
|
|
|
|
|
Default Middleware
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="4.11" data-path="coercion.html">
|
|
|
|
<a href="coercion.html">
|
|
|
|
|
|
Ring Coercion
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="4.12" data-path="route_data_validation.html">
|
|
|
|
<a href="route_data_validation.html">
|
|
|
|
|
|
Route Data Validation
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="4.13" data-path="compiling_middleware.html">
|
|
|
|
<a href="compiling_middleware.html">
|
|
|
|
|
|
Compiling Middleware
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter active" data-level="4.14" data-path="swagger.html">
|
|
|
|
<a href="swagger.html">
|
|
|
|
|
|
Swagger Support
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="4.15" data-path="RESTful_form_methods.html">
|
|
|
|
<a href="RESTful_form_methods.html">
|
|
|
|
|
|
RESTful form methods
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
<li class="header">HTTP</li>
|
|
|
|
|
|
|
|
<li class="chapter " data-level="5.1" data-path="../http/interceptors.html">
|
|
|
|
<a href="../http/interceptors.html">
|
|
|
|
|
|
Interceptors
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="5.2" data-path="../http/pedestal.html">
|
|
|
|
<a href="../http/pedestal.html">
|
|
|
|
|
|
Pedestal
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="5.3" data-path="../http/sieppari.html">
|
|
|
|
<a href="../http/sieppari.html">
|
|
|
|
|
|
Sieppari
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="5.4" data-path="../http/default_interceptors.html">
|
|
|
|
<a href="../http/default_interceptors.html">
|
|
|
|
|
|
Default Interceptors
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="5.5" data-path="../http/transforming_interceptor_chain.html">
|
|
|
|
<a href="../http/transforming_interceptor_chain.html">
|
|
|
|
|
|
Transforming Interceptor Chain
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
<li class="header">Frontend</li>
|
|
|
|
|
|
|
|
<li class="chapter " data-level="6.1" data-path="../frontend/basics.html">
|
|
|
|
<a href="../frontend/basics.html">
|
|
|
|
|
|
Basics
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="6.2" data-path="../frontend/browser.html">
|
|
|
|
<a href="../frontend/browser.html">
|
|
|
|
|
|
Browser integration
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="6.3" data-path="../frontend/controllers.html">
|
|
|
|
<a href="../frontend/controllers.html">
|
|
|
|
|
|
Controllers
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
<li class="header">Advanced</li>
|
|
|
|
|
|
|
|
<li class="chapter " data-level="7.1" data-path="../advanced/configuring_routers.html">
|
|
|
|
<a href="../advanced/configuring_routers.html">
|
|
|
|
|
|
Configuring Routers
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="7.2" data-path="../advanced/composing_routers.html">
|
|
|
|
<a href="../advanced/composing_routers.html">
|
|
|
|
|
|
Composing Routers
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="7.3" data-path="../advanced/different_routers.html">
|
|
|
|
<a href="../advanced/different_routers.html">
|
|
|
|
|
|
Different Routers
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="7.4" data-path="../advanced/route_validation.html">
|
|
|
|
<a href="../advanced/route_validation.html">
|
|
|
|
|
|
Route Validation
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="7.5" data-path="../advanced/dev_workflow.html">
|
|
|
|
<a href="../advanced/dev_workflow.html">
|
|
|
|
|
|
Dev Workflow
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="7.6" data-path="../advanced/shared_routes.html">
|
|
|
|
<a href="../advanced/shared_routes.html">
|
|
|
|
|
|
Shared Routes
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
<li class="header">Misc</li>
|
|
|
|
|
|
|
|
<li class="chapter " data-level="8.1" data-path="../performance.html">
|
|
|
|
<a href="../performance.html">
|
|
|
|
|
|
Performance
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="8.2" data-path="../development.html">
|
|
|
|
<a href="../development.html">
|
|
|
|
|
|
Development Instructions
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li class="chapter " data-level="8.3" data-path="../faq.html">
|
|
|
|
<a href="../faq.html">
|
|
|
|
|
|
FAQ
|
|
|
|
</a>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
<li class="divider"></li>
|
|
|
|
<li>
|
|
<a href="https://www.gitbook.com" target="blank" class="gitbook-link">
|
|
Published with GitBook
|
|
</a>
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
</nav>
|
|
|
|
|
|
</div>
|
|
|
|
<div class="book-body">
|
|
|
|
<div class="body-inner">
|
|
|
|
|
|
|
|
<div class="book-header" role="navigation">
|
|
|
|
|
|
<!-- Title -->
|
|
<h1>
|
|
<i class="fa fa-circle-o-notch fa-spin"></i>
|
|
<a href=".." >Swagger Support</a>
|
|
</h1>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="page-wrapper" tabindex="-1" role="main">
|
|
<div class="page-inner">
|
|
|
|
<div id="book-search-results">
|
|
<div class="search-noresults">
|
|
|
|
<section class="normal markdown-section">
|
|
|
|
<h1 id="swagger-support">Swagger Support</h1>
|
|
<pre><code>[metosin/reitit-swagger "0.3.1"]
|
|
</code></pre><p>Reitit supports <a href="https://swagger.io/" target="_blank">Swagger2</a> documentation, thanks to <a href="https://github.com/metosin/schema-tools" target="_blank">schema-tools</a> and <a href="https://github.com/metosin/spec-tools" target="_blank">spec-tools</a>. Documentation is extracted from route definitions, coercion <code>:parameters</code> and <code>:responses</code> and from a set of new documentation keys.</p>
|
|
<p>To enable swagger-documentation for a ring-router:</p>
|
|
<ol>
|
|
<li>annotate your routes with swagger-data</li>
|
|
<li>mount a swagger-handler to serve the swagger-spec</li>
|
|
<li>optionally mount a swagger-ui to visualize the swagger-spec</li>
|
|
</ol>
|
|
<h2 id="swagger-data">Swagger data</h2>
|
|
<p>The following route data keys contribute to the generated swagger specification:</p>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>key</th>
|
|
<th>description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>:swagger</td>
|
|
<td>map of any swagger-data. Can have <code>:id</code> (keyword or sequence of keywords) to identify the api</td>
|
|
</tr>
|
|
<tr>
|
|
<td>:no-doc</td>
|
|
<td>optional boolean to exclude endpoint from api docs</td>
|
|
</tr>
|
|
<tr>
|
|
<td>:tags</td>
|
|
<td>optional set of strings of keywords tags for an endpoint api docs</td>
|
|
</tr>
|
|
<tr>
|
|
<td>:summary</td>
|
|
<td>optional short string summary of an endpoint</td>
|
|
</tr>
|
|
<tr>
|
|
<td>:description</td>
|
|
<td>optional long description of an endpoint. Supports <a href="http://spec.commonmark.org/" target="_blank">http://spec.commonmark.org/</a></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Coercion keys also contribute to the docs:</p>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>key</th>
|
|
<th>description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>:parameters</td>
|
|
<td>optional input parameters for a route, in a format defined by the coercion</td>
|
|
</tr>
|
|
<tr>
|
|
<td>:responses</td>
|
|
<td>optional descriptions of responess, in a format defined by coercion</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>There is a <code>reitit.swagger.swagger-feature</code>, which acts as both a <code>Middleware</code> and an <code>Interceptor</code> that is not participating in any request processing - it just defines the route data specs for the routes it's mounted to. It is only needed if the <a href="route_data_validation.html">route data validation</a> is turned on.</p>
|
|
<h2 id="swagger-spec">Swagger spec</h2>
|
|
<p>To serve the actual <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md" target="_blank">Swagger Specification</a>, there is <code>reitit.swagger/create-swagger-handler</code>. It takes no arguments and returns a ring-handler which collects at request-time data from all routes for the same swagger api and returns a formatted Swagger specification as Clojure data, to be encoded by a response formatter.</p>
|
|
<p>If you need to post-process the generated spec, just wrap the handler with a custom <code>Middleware</code> or an <code>Interceptor</code>.</p>
|
|
<h2 id="swagger-ui">Swagger-ui</h2>
|
|
<p><a href="https://github.com/swagger-api/swagger-ui" target="_blank">Swagger-ui</a> is a user interface to visualize and interact with the Swagger specification. To make things easy, there is a pre-integrated version of the swagger-ui as a separate module.</p>
|
|
<pre><code>[metosin/reitit-swagger-ui "0.3.1"]
|
|
</code></pre><p><code>reitit.swagger-ui/create-swagger-ui-hander</code> can be used to create a ring-handler to serve the swagger-ui. It accepts the following options:</p>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>key</th>
|
|
<th>description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>:parameter</td>
|
|
<td>optional name of the wildcard parameter, defaults to unnamed keyword <code>:</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>:root</td>
|
|
<td>optional resource root, defaults to <code>"swagger-ui"</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>:url</td>
|
|
<td>path to swagger endpoint, defaults to <code>/swagger.json</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>:path</td>
|
|
<td>optional path to mount the handler to. Works only if mounted outside of a router.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>:config</td>
|
|
<td>parameters passed to swaggger-ui as-is. See <a href="https://github.com/swagger-api/swagger-ui/tree/2.x#parameters" target="_blank">the docs</a></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>We use swagger-ui from <a href="https://github.com/metosin/ring-swagger-ui" target="_blank">ring-swagger-ui</a>, which can be easily configured from routing application. It stores files <code>swagger-ui</code> in the resource classpath.</p>
|
|
<p>Webjars also hosts a <a href="https://github.com/webjars/swagger-ui" target="_blank">version</a> of the swagger-ui.</p>
|
|
<p><strong>NOTE</strong>: Currently, swagger-ui module is just for Clojure. ClojureScript-support welcome as a PR!</p>
|
|
<h2 id="examples">Examples</h2>
|
|
<h3 id="simple-example">Simple example</h3>
|
|
<ul>
|
|
<li>two routes</li>
|
|
<li>swagger-spec served from <code>"/swagger.json"</code></li>
|
|
<li>swagger-ui mounted to <code>"/api-docs"</code></li>
|
|
<li>note that for real-world use, you need a <a href="default_middleware.html#content-negotiation">content-negation middleware</a> -
|
|
see the next example</li>
|
|
</ul>
|
|
<pre><code class="lang-clj">(<span class="hljs-name">require</span> '[reitit.ring <span class="hljs-symbol">:as</span> ring])
|
|
(<span class="hljs-name">require</span> '[reitit.swagger <span class="hljs-symbol">:as</span> swagger])
|
|
(<span class="hljs-name">require</span> '[reitit.swagger-ui <span class="hljs-symbol">:as</span> swagger-ui])
|
|
|
|
(<span class="hljs-name"><span class="hljs-builtin-name">def</span></span> app
|
|
(<span class="hljs-name">ring/ring-handler</span>
|
|
(<span class="hljs-name">ring/router</span>
|
|
[[<span class="hljs-string">"/api"</span>
|
|
[<span class="hljs-string">"/ping"</span> {<span class="hljs-symbol">:get</span> (<span class="hljs-name"><span class="hljs-builtin-name">constantly</span></span> {<span class="hljs-symbol">:status</span> <span class="hljs-number">200</span>, <span class="hljs-symbol">:body</span> <span class="hljs-string">"ping"</span>})}]
|
|
[<span class="hljs-string">"/pong"</span> {<span class="hljs-symbol">:post</span> (<span class="hljs-name"><span class="hljs-builtin-name">constantly</span></span> {<span class="hljs-symbol">:status</span> <span class="hljs-number">200</span>, <span class="hljs-symbol">:body</span> <span class="hljs-string">"pong"</span>})}]]
|
|
[<span class="hljs-string">""</span> {<span class="hljs-symbol">:no-doc</span> <span class="hljs-literal">true</span>}
|
|
[<span class="hljs-string">"/swagger.json"</span> {<span class="hljs-symbol">:get</span> (<span class="hljs-name">swagger/create-swagger-handler</span>)}]
|
|
[<span class="hljs-string">"/api-docs/*"</span> {<span class="hljs-symbol">:get</span> (<span class="hljs-name">swagger-ui/create-swagger-ui-handler</span>)}]]])))
|
|
</code></pre>
|
|
<p>The generated swagger spec:</p>
|
|
<pre><code class="lang-clj">(<span class="hljs-name">app</span> {<span class="hljs-symbol">:request-method</span> <span class="hljs-symbol">:get</span> <span class="hljs-symbol">:uri</span> <span class="hljs-string">"/swagger.json"</span>})
|
|
<span class="hljs-comment">;{:status 200</span>
|
|
<span class="hljs-comment">; :body {:swagger "2.0"</span>
|
|
<span class="hljs-comment">; :x-id #{:reitit.swagger/default}</span>
|
|
<span class="hljs-comment">; :paths {"/api/ping" {:get {}}</span>
|
|
<span class="hljs-comment">; "/api/pong" {:post {}}}}}</span>
|
|
</code></pre>
|
|
<p>Swagger-ui:</p>
|
|
<pre><code class="lang-clj">(<span class="hljs-name">app</span> {<span class="hljs-symbol">:request-method</span> <span class="hljs-symbol">:get</span>, <span class="hljs-symbol">:uri</span> <span class="hljs-string">"/api-docs/index.html"</span>})
|
|
<span class="hljs-comment">; ... the swagger-ui index-page, configured correctly</span>
|
|
</code></pre>
|
|
<p>You might be interested in adding a <a href="slash_handler.html">trailing slash handler</a> to the app to serve the swagger-ui from <code>/api-docs</code> (without the trailing slash) too.</p>
|
|
<p>Another way to serve the swagger-ui is using the <a href="default_handler.html">default handler</a>:</p>
|
|
<pre><code class="lang-clj">(<span class="hljs-name"><span class="hljs-builtin-name">def</span></span> app
|
|
(<span class="hljs-name">ring/ring-handler</span>
|
|
(<span class="hljs-name">ring/router</span>
|
|
[[<span class="hljs-string">"/api"</span>
|
|
[<span class="hljs-string">"/ping"</span> {<span class="hljs-symbol">:get</span> (<span class="hljs-name"><span class="hljs-builtin-name">constantly</span></span> {<span class="hljs-symbol">:status</span> <span class="hljs-number">200</span>, <span class="hljs-symbol">:body</span> <span class="hljs-string">"ping"</span>})}]
|
|
[<span class="hljs-string">"/pong"</span> {<span class="hljs-symbol">:post</span> (<span class="hljs-name"><span class="hljs-builtin-name">constantly</span></span> {<span class="hljs-symbol">:status</span> <span class="hljs-number">200</span>, <span class="hljs-symbol">:body</span> <span class="hljs-string">"pong"</span>})}]]
|
|
[<span class="hljs-string">"/swagger.json"</span>
|
|
{<span class="hljs-symbol">:get</span> {<span class="hljs-symbol">:no-doc</span> <span class="hljs-literal">true</span>
|
|
<span class="hljs-symbol">:handler</span> (<span class="hljs-name">swagger/create-swagger-handler</span>)}}]])
|
|
(<span class="hljs-name">swagger-ui/create-swagger-ui-handler</span> {<span class="hljs-symbol">:path</span> <span class="hljs-string">"/api-docs"</span>})))
|
|
</code></pre>
|
|
<h3 id="more-complete-example">More complete example</h3>
|
|
<ul>
|
|
<li><code>clojure.spec</code> coercion</li>
|
|
<li>swagger data (<code>:tags</code>, <code>:produces</code>, <code>:summary</code>, <code>:basePath</code>)</li>
|
|
<li>swagger-spec served from <code>"/swagger.json"</code></li>
|
|
<li>swagger-ui mounted to <code>"/"</code></li>
|
|
<li>set of middleware for content negotiation, exceptions, multipart etc.</li>
|
|
<li>missed routes are handled by <code>create-default-handler</code></li>
|
|
<li>served via <a href="https://github.com/ring-clojure/ring/tree/master/ring-jetty-adapter" target="_blank">ring-jetty</a></li>
|
|
</ul>
|
|
<p>Whole example project is in <a href="https://github.com/metosin/reitit/tree/master/examples/ring-swagger" target="_blank"><code>/examples/ring-swagger</code></a>.</p>
|
|
<pre><code class="lang-clj">(<span class="hljs-name"><span class="hljs-builtin-name">ns</span></span> example.server
|
|
(<span class="hljs-symbol">:require</span> [reitit.ring <span class="hljs-symbol">:as</span> ring]
|
|
[reitit.swagger <span class="hljs-symbol">:as</span> swagger]
|
|
[reitit.swagger-ui <span class="hljs-symbol">:as</span> swagger-ui]
|
|
[reitit.ring.coercion <span class="hljs-symbol">:as</span> coercion]
|
|
[reitit.coercion.spec]
|
|
[reitit.ring.middleware.muuntaja <span class="hljs-symbol">:as</span> muuntaja]
|
|
[reitit.ring.middleware.exception <span class="hljs-symbol">:as</span> exception]
|
|
[reitit.ring.middleware.multipart <span class="hljs-symbol">:as</span> multipart]
|
|
[reitit.ring.middleware.parameters <span class="hljs-symbol">:as</span> parameters]
|
|
[ring.middleware.params <span class="hljs-symbol">:as</span> params]
|
|
[ring.adapter.jetty <span class="hljs-symbol">:as</span> jetty]
|
|
[muuntaja.core <span class="hljs-symbol">:as</span> m]
|
|
[clojure.java.io <span class="hljs-symbol">:as</span> io]))
|
|
|
|
(<span class="hljs-name"><span class="hljs-builtin-name">def</span></span> app
|
|
(<span class="hljs-name">ring/ring-handler</span>
|
|
(<span class="hljs-name">ring/router</span>
|
|
[[<span class="hljs-string">"/swagger.json"</span>
|
|
{<span class="hljs-symbol">:get</span> {<span class="hljs-symbol">:no-doc</span> <span class="hljs-literal">true</span>
|
|
<span class="hljs-symbol">:swagger</span> {<span class="hljs-symbol">:info</span> {<span class="hljs-symbol">:title</span> <span class="hljs-string">"my-api"</span>}
|
|
<span class="hljs-symbol">:basePath</span> <span class="hljs-string">"/"</span>} <span class="hljs-comment">;; prefix for all paths</span>
|
|
<span class="hljs-symbol">:handler</span> (<span class="hljs-name">swagger/create-swagger-handler</span>)}}]
|
|
|
|
[<span class="hljs-string">"/files"</span>
|
|
{<span class="hljs-symbol">:swagger</span> {<span class="hljs-symbol">:tags</span> [<span class="hljs-string">"files"</span>]}}
|
|
|
|
[<span class="hljs-string">"/upload"</span>
|
|
{<span class="hljs-symbol">:post</span> {<span class="hljs-symbol">:summary</span> <span class="hljs-string">"upload a file"</span>
|
|
<span class="hljs-symbol">:parameters</span> {<span class="hljs-symbol">:multipart</span> {<span class="hljs-symbol">:file</span> multipart/temp-file-part}}
|
|
<span class="hljs-symbol">:responses</span> {<span class="hljs-number">200</span> {<span class="hljs-symbol">:body</span> {<span class="hljs-symbol">:file</span> multipart/temp-file-part}}}
|
|
<span class="hljs-symbol">:handler</span> (<span class="hljs-name"><span class="hljs-builtin-name">fn</span></span> [{{{<span class="hljs-symbol">:keys</span> [file]} <span class="hljs-symbol">:multipart</span>} <span class="hljs-symbol">:parameters</span>}]
|
|
{<span class="hljs-symbol">:status</span> <span class="hljs-number">200</span>
|
|
<span class="hljs-symbol">:body</span> {<span class="hljs-symbol">:file</span> file}})}}]
|
|
|
|
[<span class="hljs-string">"/download"</span>
|
|
{<span class="hljs-symbol">:get</span> {<span class="hljs-symbol">:summary</span> <span class="hljs-string">"downloads a file"</span>
|
|
<span class="hljs-symbol">:swagger</span> {<span class="hljs-symbol">:produces</span> [<span class="hljs-string">"image/png"</span>]}
|
|
<span class="hljs-symbol">:handler</span> (<span class="hljs-name"><span class="hljs-builtin-name">fn</span></span> [_]
|
|
{<span class="hljs-symbol">:status</span> <span class="hljs-number">200</span>
|
|
<span class="hljs-symbol">:headers</span> {<span class="hljs-string">"Content-Type"</span> <span class="hljs-string">"image/png"</span>}
|
|
<span class="hljs-symbol">:body</span> (<span class="hljs-name">io/input-stream</span> (<span class="hljs-name">io/resource</span> <span class="hljs-string">"reitit.png"</span>))})}}]]
|
|
|
|
[<span class="hljs-string">"/math"</span>
|
|
{<span class="hljs-symbol">:swagger</span> {<span class="hljs-symbol">:tags</span> [<span class="hljs-string">"math"</span>]}}
|
|
|
|
[<span class="hljs-string">"/plus"</span>
|
|
{<span class="hljs-symbol">:get</span> {<span class="hljs-symbol">:summary</span> <span class="hljs-string">"plus with spec query parameters"</span>
|
|
<span class="hljs-symbol">:parameters</span> {<span class="hljs-symbol">:query</span> {<span class="hljs-symbol">:x</span> int?, <span class="hljs-symbol">:y</span> int?}}
|
|
<span class="hljs-symbol">:responses</span> {<span class="hljs-number">200</span> {<span class="hljs-symbol">:body</span> {<span class="hljs-symbol">:total</span> int?}}}
|
|
<span class="hljs-symbol">:handler</span> (<span class="hljs-name"><span class="hljs-builtin-name">fn</span></span> [{{{<span class="hljs-symbol">:keys</span> [x y]} <span class="hljs-symbol">:query</span>} <span class="hljs-symbol">:parameters</span>}]
|
|
{<span class="hljs-symbol">:status</span> <span class="hljs-number">200</span>
|
|
<span class="hljs-symbol">:body</span> {<span class="hljs-symbol">:total</span> (<span class="hljs-name"><span class="hljs-builtin-name">+</span></span> x y)}})}
|
|
<span class="hljs-symbol">:post</span> {<span class="hljs-symbol">:summary</span> <span class="hljs-string">"plus with spec body parameters"</span>
|
|
<span class="hljs-symbol">:parameters</span> {<span class="hljs-symbol">:body</span> {<span class="hljs-symbol">:x</span> int?, <span class="hljs-symbol">:y</span> int?}}
|
|
<span class="hljs-symbol">:responses</span> {<span class="hljs-number">200</span> {<span class="hljs-symbol">:body</span> {<span class="hljs-symbol">:total</span> int?}}}
|
|
<span class="hljs-symbol">:handler</span> (<span class="hljs-name"><span class="hljs-builtin-name">fn</span></span> [{{{<span class="hljs-symbol">:keys</span> [x y]} <span class="hljs-symbol">:body</span>} <span class="hljs-symbol">:parameters</span>}]
|
|
{<span class="hljs-symbol">:status</span> <span class="hljs-number">200</span>
|
|
<span class="hljs-symbol">:body</span> {<span class="hljs-symbol">:total</span> (<span class="hljs-name"><span class="hljs-builtin-name">+</span></span> x y)}})}}]]]
|
|
|
|
{<span class="hljs-symbol">:data</span> {<span class="hljs-symbol">:coercion</span> reitit.coercion.spec/coercion
|
|
<span class="hljs-symbol">:muuntaja</span> m/instance
|
|
<span class="hljs-symbol">:middleware</span> [<span class="hljs-comment">;; query-params & form-params</span>
|
|
parameters/parameters-middleware
|
|
<span class="hljs-comment">;; content-negotiation</span>
|
|
muuntaja/format-negotiate-middleware
|
|
<span class="hljs-comment">;; encoding response body</span>
|
|
muuntaja/format-response-middleware
|
|
<span class="hljs-comment">;; exception handling</span>
|
|
exception/exception-middleware
|
|
<span class="hljs-comment">;; decoding request body</span>
|
|
muuntaja/format-request-middleware
|
|
<span class="hljs-comment">;; coercing response bodys</span>
|
|
coercion/coerce-response-middleware
|
|
<span class="hljs-comment">;; coercing request parameters</span>
|
|
coercion/coerce-request-middleware
|
|
<span class="hljs-comment">;; multipart</span>
|
|
multipart/multipart-middleware]}})
|
|
(<span class="hljs-name">ring/routes</span>
|
|
(<span class="hljs-name">swagger-ui/create-swagger-ui-handler</span> {<span class="hljs-symbol">:path</span> <span class="hljs-string">"/"</span>})
|
|
(<span class="hljs-name">ring/create-default-handler</span>))))
|
|
|
|
(<span class="hljs-name"><span class="hljs-builtin-name">defn</span></span> start []
|
|
(<span class="hljs-name">jetty/run-jetty</span> #'app {<span class="hljs-symbol">:port</span> <span class="hljs-number">3000</span>, <span class="hljs-symbol">:join?</span> <span class="hljs-literal">false</span>})
|
|
(<span class="hljs-name">println</span> <span class="hljs-string">"server running in port 3000"</span>))
|
|
</code></pre>
|
|
<p><a href="http://localhost:3000" target="_blank">http://localhost:3000</a> should render now the swagger-ui:</p>
|
|
<p><img src="../images/swagger.png" alt="Swagger-ui"></p>
|
|
<h2 id="multiple-swagger-apis">Multiple swagger apis</h2>
|
|
<p>There can be multiple swagger apis within a router. Each route can be part of 0..n swagger apis. Swagger apis are identified by value in route data under key path <code>[:swagger :id]</code>. It can be either a keyword or a sequence of keywords. Normal route data <a href="../basics/route_data.html#nested-route-data">scoping rules</a> rules apply.</p>
|
|
<p>Example with:</p>
|
|
<ul>
|
|
<li>4 routes</li>
|
|
<li>2 swagger apis <code>::one</code> and <code>::two</code></li>
|
|
<li>3 swagger specs</li>
|
|
</ul>
|
|
<pre><code class="lang-clj">(<span class="hljs-name">require</span> '[reitit.ring <span class="hljs-symbol">:as</span> ring])
|
|
(<span class="hljs-name">require</span> '[reitit.swagger <span class="hljs-symbol">:as</span> swagger])
|
|
|
|
(<span class="hljs-name"><span class="hljs-builtin-name">def</span></span> ping-route
|
|
[<span class="hljs-string">"/ping"</span> {<span class="hljs-symbol">:get</span> (<span class="hljs-name"><span class="hljs-builtin-name">constantly</span></span> {<span class="hljs-symbol">:status</span> <span class="hljs-number">200</span>, <span class="hljs-symbol">:body</span> <span class="hljs-string">"ping"</span>})}])
|
|
|
|
(<span class="hljs-name"><span class="hljs-builtin-name">def</span></span> spec-route
|
|
[<span class="hljs-string">"/swagger.json"</span>
|
|
{<span class="hljs-symbol">:get</span> {<span class="hljs-symbol">:no-doc</span> <span class="hljs-literal">true</span>
|
|
<span class="hljs-symbol">:handler</span> (<span class="hljs-name">swagger/create-swagger-handler</span>)}}])
|
|
|
|
(<span class="hljs-name"><span class="hljs-builtin-name">def</span></span> app
|
|
(<span class="hljs-name">ring/ring-handler</span>
|
|
(<span class="hljs-name">ring/router</span>
|
|
[[<span class="hljs-string">"/common"</span> {<span class="hljs-symbol">:swagger</span> {<span class="hljs-symbol">:id</span> #{<span class="hljs-symbol">::one</span> <span class="hljs-symbol">::two</span>}}} ping-route]
|
|
[<span class="hljs-string">"/one"</span> {<span class="hljs-symbol">:swagger</span> {<span class="hljs-symbol">:id</span> <span class="hljs-symbol">::one</span>}} ping-route spec-route]
|
|
[<span class="hljs-string">"/two"</span> {<span class="hljs-symbol">:swagger</span> {<span class="hljs-symbol">:id</span> <span class="hljs-symbol">::two</span>}} ping-route spec-route
|
|
[<span class="hljs-string">"/deep"</span> {<span class="hljs-symbol">:swagger</span> {<span class="hljs-symbol">:id</span> <span class="hljs-symbol">::one</span>}} ping-route]]
|
|
[<span class="hljs-string">"/one-two"</span> {<span class="hljs-symbol">:swagger</span> {<span class="hljs-symbol">:id</span> #{<span class="hljs-symbol">::one</span> <span class="hljs-symbol">::two</span>}}} spec-route]])))
|
|
</code></pre>
|
|
<pre><code class="lang-clj">(<span class="hljs-name"><span class="hljs-builtin-name">-></span></span> {<span class="hljs-symbol">:request-method</span> <span class="hljs-symbol">:get</span>, <span class="hljs-symbol">:uri</span> <span class="hljs-string">"/one/swagger.json"</span>} app <span class="hljs-symbol">:body</span> <span class="hljs-symbol">:paths</span> keys)
|
|
<span class="hljs-comment">; ("/common/ping" "/one/ping" "/two/deep/ping")</span>
|
|
</code></pre>
|
|
<pre><code class="lang-clj">(<span class="hljs-name"><span class="hljs-builtin-name">-></span></span> {<span class="hljs-symbol">:request-method</span> <span class="hljs-symbol">:get</span>, <span class="hljs-symbol">:uri</span> <span class="hljs-string">"/two/swagger.json"</span>} app <span class="hljs-symbol">:body</span> <span class="hljs-symbol">:paths</span> keys)
|
|
<span class="hljs-comment">; ("/common/ping" "/two/ping")</span>
|
|
</code></pre>
|
|
<pre><code class="lang-clj">(<span class="hljs-name"><span class="hljs-builtin-name">-></span></span> {<span class="hljs-symbol">:request-method</span> <span class="hljs-symbol">:get</span>, <span class="hljs-symbol">:uri</span> <span class="hljs-string">"/one-two/swagger.json"</span>} app <span class="hljs-symbol">:body</span> <span class="hljs-symbol">:paths</span> keys)
|
|
<span class="hljs-comment">; ("/common/ping" "/one/ping" "/two/ping" "/two/deep/ping")</span>
|
|
</code></pre>
|
|
<h3 id="todo">TODO</h3>
|
|
<ul>
|
|
<li>ClojureScript<ul>
|
|
<li>example for <a href="https://github.com/macchiato-framework" target="_blank">Macchiato</a></li>
|
|
<li>body formatting</li>
|
|
<li>resource handling</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
</section>
|
|
|
|
</div>
|
|
<div class="search-results">
|
|
<div class="has-results">
|
|
|
|
<h1 class="search-results-title"><span class='search-results-count'></span> results matching "<span class='search-query'></span>"</h1>
|
|
<ul class="search-results-list"></ul>
|
|
|
|
</div>
|
|
<div class="no-results">
|
|
|
|
<h1 class="search-results-title">No results matching "<span class='search-query'></span>"</h1>
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
<a href="compiling_middleware.html" class="navigation navigation-prev " aria-label="Previous page: Compiling Middleware">
|
|
<i class="fa fa-angle-left"></i>
|
|
</a>
|
|
|
|
|
|
<a href="RESTful_form_methods.html" class="navigation navigation-next " aria-label="Next page: RESTful form methods">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
|
|
|
|
|
|
</div>
|
|
|
|
<script>
|
|
var gitbook = gitbook || [];
|
|
gitbook.push(function() {
|
|
gitbook.page.hasChanged({"page":{"title":"Swagger Support","level":"4.14","depth":1,"next":{"title":"RESTful form methods","level":"4.15","depth":1,"path":"ring/RESTful_form_methods.md","ref":"ring/RESTful_form_methods.md","articles":[]},"previous":{"title":"Compiling Middleware","level":"4.13","depth":1,"path":"ring/compiling_middleware.md","ref":"ring/compiling_middleware.md","articles":[]},"dir":"ltr"},"config":{"plugins":["hints","editlink","github","highlight"],"root":"doc","styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"github":{"url":"https://github.com/metosin/reitit"},"editlink":{"label":"Edit This Page","multilingual":false,"base":"https://github.com/metosin/reitit/tree/master/doc"},"search":{},"hints":{"danger":"fa fa-exclamation-circle","info":"fa fa-info-circle","tip":"fa fa-mortar-board","working":"fa fa-wrench"},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"fontsettings":{"theme":"white","family":"sans","size":2},"highlight":{},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"gitbook":"*"},"file":{"path":"ring/swagger.md","mtime":"2019-05-01T19:24:47.401Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2019-05-01T19:25:16.365Z"},"basePath":"..","book":{"language":""}});
|
|
});
|
|
</script>
|
|
</div>
|
|
|
|
|
|
<script src="../gitbook/gitbook.js"></script>
|
|
<script src="../gitbook/theme.js"></script>
|
|
|
|
|
|
<script src="../gitbook/gitbook-plugin-editlink/plugin.js"></script>
|
|
|
|
|
|
|
|
<script src="../gitbook/gitbook-plugin-github/plugin.js"></script>
|
|
|
|
|
|
|
|
<script src="../gitbook/gitbook-plugin-search/search-engine.js"></script>
|
|
|
|
|
|
|
|
<script src="../gitbook/gitbook-plugin-search/search.js"></script>
|
|
|
|
|
|
|
|
<script src="../gitbook/gitbook-plugin-lunr/lunr.min.js"></script>
|
|
|
|
|
|
|
|
<script src="../gitbook/gitbook-plugin-lunr/search-lunr.js"></script>
|
|
|
|
|
|
|
|
<script src="../gitbook/gitbook-plugin-sharing/buttons.js"></script>
|
|
|
|
|
|
|
|
<script src="../gitbook/gitbook-plugin-fontsettings/fontsettings.js"></script>
|
|
|
|
|
|
|
|
</body>
|
|
</html>
|
|
|