111 lines
16 KiB
HTML
111 lines
16 KiB
HTML
<html>
|
|
<head>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1" charset="UTF-8">
|
|
<title>io.bkbn.kompendium.core</title>
|
|
</head><body><link href="../../images/logo-icon.svg" rel="icon" type="image/svg"><script>var pathToRoot = "../../";</script>
|
|
<script type="text/javascript" src="../../scripts/sourceset_dependencies.js" async></script><link href="../../styles/style.css" rel="Stylesheet"><link href="../../styles/jetbrains-mono.css" rel="Stylesheet"><link href="../../styles/main.css" rel="Stylesheet"><link href="../../styles/prism.css" rel="Stylesheet"><link href="../../styles/logo-styles.css" rel="Stylesheet"><script type="text/javascript" src="../../scripts/clipboard.js" async></script><script type="text/javascript" src="../../scripts/navigation-loader.js" async></script><script type="text/javascript" src="../../scripts/platform-content-handler.js" async></script><script type="text/javascript" src="../../scripts/main.js" defer></script><script type="text/javascript" src="../../scripts/prism.js" async></script><link href="../../styles/multimodule.css" rel="Stylesheet"><script>const storage = localStorage.getItem("dokka-dark-mode")
|
|
const savedDarkMode = storage ? JSON.parse(storage) : false
|
|
if(savedDarkMode === true){
|
|
document.getElementsByTagName("html")[0].classList.add("theme-dark")
|
|
}</script>
|
|
|
|
|
|
<div class="navigation-wrapper" id="navigation-wrapper">
|
|
<div id="leftToggler"><span class="icon-toggler"></span></div>
|
|
<div class="library-name"><a href="../../index.html"><span>kompendium</span></a></div>
|
|
<div><dokka-template-command data="{"@class":"org.jetbrains.dokka.base.templating.ReplaceVersionsCommand","location":"io.bkbn.kompendium.core/index.html"}"><div class="versions-dropdown">
|
|
<div class="versions-dropdown-button">2.0.4</div>
|
|
<div class="versions-dropdown-data"><a href="index.html">2.0.4</a><a href="../../older/2.0.3/kompendium-core/io.bkbn.kompendium.core/index.html">2.0.3</a><a href="../../older/2.0.2/kompendium-core/io.bkbn.kompendium.core/index.html">2.0.2</a><a href="../../older/2.0.1/kompendium-core/io.bkbn.kompendium.core/index.html">2.0.1</a></div>
|
|
</div>
|
|
</dokka-template-command></div>
|
|
<div class="pull-right d-flex"><button id="theme-toggle-button"><span id="theme-toggle"></span></button>
|
|
<div id="searchBar"></div>
|
|
</div>
|
|
</div>
|
|
<div id="container">
|
|
<div id="leftColumn">
|
|
<div id="sideMenu"></div>
|
|
</div>
|
|
<div id="main">
|
|
<div class="main-content" id="content" pageids="kompendium-core::io.bkbn.kompendium.core////PointingToDeclaration//-1397293861">
|
|
<div class="breadcrumbs"><a href="../index.html">kompendium-core</a>/<a href="index.html">io.bkbn.kompendium.core</a></div>
|
|
<div class="cover ">
|
|
<h1 class="cover"><span>Package io.</span><wbr><span>bkbn.</span><wbr><span>kompendium.</span><wbr><span>core</span></h1>
|
|
<div class="platform-hinted UnderCoverText" data-platform-hinted="data-platform-hinted"><div class="content sourceset-depenent-content" data-active="" data-togglable=":kompendium-core:dokkaHtmlPartial/main"><p class="paragraph">The root package contains several objects that power Kompendium, including the Kompendium Ktor Plugin, route notarization methods, and the reflection engine that analyzes method info type parameters.</p><h2 class=""> Plugin</h2><p class="paragraph">The Kompendium plugin is an extremely light-weight plugin, with only a couple areas of customization.</p><h3 class=""> Serialization</h3><p class="paragraph">Kompendium relies on your API to provide a properly-configured <code class="lang-kotlin">ContentNegotiator</code> in order to convert the <code class="lang-kotlin">OpenApiSpec</code> into JSON. The advantage to this approach is that all of your data classes will be serialized precisely how you define. The downside is that issues could exist in serialization frameworks that have not been tested. At the moment, Jackson, Gson and KotlinX serialization have all been tested. If you run into any serialization issues, particularly with a serializer not listed above, please open an issue on GitHub 🙏</p><p class="paragraph">Note for Kotlinx ⚠️</p><p class="paragraph">You will need to include the <code class="lang-kotlin">SerializersModule</code> provided in <code class="lang-kotlin">KompendiumSerializersModule</code> in order to serialize any provided defaults. This comes down to how Kotlinx expects users to handle serializing <code class="lang-kotlin">Any</code>. Essentially, this serializer module will convert any <code class="lang-kotlin">Any</code> serialization to be <code class="lang-kotlin">Contextual</code>. This is pretty hacky, but seemed to be the only way to get Kotlinx to play nice with serializing <code class="lang-kotlin">Any</code>. If you come up with a better solution, definitely go ahead and open up a PR!</p><h2 class=""> Notarization</h2><p class="paragraph">Central to Kompendium is the concept of notarization.</p><p class="paragraph">Notarizing a route is the mechanism by which Kompendium analyzes your route types, along with provided metadata, and converts to the expected OpenAPI format.</p><p class="paragraph">Before jumping into notarization, lets first look at a standard Ktor route</p><div class="sample-container"><pre><code class="block lang-kotlin" theme="idea">routing {<br> get {<br> call.respond(HttpStatusCode.OK, BasicResponse(c = UUID.randomUUID().toString()))<br> }<br>}</code></pre><span class="top-right-position"><span class="copy-icon"></span><div class="copy-popup-wrapper popup-to-left"><span class="copy-popup-icon"></span><span>Content copied to clipboard</span></div></span></div><p class="paragraph">Now, let's compare this to the same functionality, but notarized using Kompendium</p><div class="sample-container"><pre><code class="block lang-kotlin" theme="idea">routing {<br> notarizedGet(simpleGetExample) {<br> call.respond(HttpStatusCode.OK, BasicResponse(c = UUID.randomUUID().toString()))<br> }<br>}</code></pre><span class="top-right-position"><span class="copy-icon"></span><div class="copy-popup-wrapper popup-to-left"><span class="copy-popup-icon"></span><span>Content copied to clipboard</span></div></span></div><p class="paragraph">Pretty simple huh. But hold on... what is this <code class="lang-kotlin">simpleGetExample</code>? How can I know that it is so "simple". Let's take a look</p><div class="sample-container"><pre><code class="block lang-kotlin" theme="idea">val simpleGetExample = GetInfo<Unit, BasicResponse>(<br> summary = "Simple, Documented GET Request",<br> description = "This is to showcase just how easy it is to document your Ktor API!",<br> responseInfo = ResponseInfo(<br> status = HttpStatusCode.OK,<br> description = "This means everything went as expected!",<br> examples = mapOf("demo" to BasicResponse(c = "52c099d7-8642-46cc-b34e-22f39b923cf4"))<br> ),<br> tags = setOf("Simple")<br>)</code></pre><span class="top-right-position"><span class="copy-icon"></span><div class="copy-popup-wrapper popup-to-left"><span class="copy-popup-icon"></span><span>Content copied to clipboard</span></div></span></div><p class="paragraph">See, not so bad 😄 <code class="lang-kotlin">GetInfo<*,*></code> is an implementation of <code class="lang-kotlin">MethodInfo<TParam, TResp></code>, a sealed interface designed to encapsulate all the metadata required for documenting an API route. Kompendium leverages this data, along with the provided type parameters <code class="lang-kotlin">TParam</code> and <code class="lang-kotlin">TResp</code> to construct the full OpenAPI Specification for your route.</p><p class="paragraph">Additionally, just as a backup, each notarization method includes a "post-processing' hook that will allow you to have final say in the generated route info prior to being attached to the spec. This can be accessed via the optional parameter</p><div class="sample-container"><pre><code class="block lang-kotlin" theme="idea">routing {<br> notarizedGet(simpleGetExample, postProcess = { spec -> spec }) {<br> call.respond(HttpStatusCode.OK, BasicResponse(c = UUID.randomUUID().toString()))<br> }<br>}</code></pre><span class="top-right-position"><span class="copy-icon"></span><div class="copy-popup-wrapper popup-to-left"><span class="copy-popup-icon"></span><span>Content copied to clipboard</span></div></span></div><p class="paragraph">This should only be used in <i>extremely</i> rare scenarios, but it is nice to know it is there if you need it.</p></div></div>
|
|
</div>
|
|
<div class="tabbedcontent">
|
|
<div class="tabs-section" tabs-section="tabs-section"><button class="section-tab" data-active="" data-togglable="Types">Types</button></div>
|
|
<div class="tabs-section-body">
|
|
<h2 class="">Types</h2>
|
|
<div class="table" data-togglable="Types"><a data-name="-1039470044%2FClasslikes%2F-1397293861" anchor-label="Kompendium" id="-1039470044%2FClasslikes%2F-1397293861" data-filterable-set=":kompendium-core:dokkaHtmlPartial/main"></a>
|
|
<div class="table-row" data-filterable-current=":kompendium-core:dokkaHtmlPartial/main" data-filterable-set=":kompendium-core:dokkaHtmlPartial/main">
|
|
<div class="main-subrow keyValue ">
|
|
<div class=""><span class="inline-flex">
|
|
<div><a href="-kompendium/index.html"><span><span>Kompendium</span></span></a></div>
|
|
<span class="anchor-wrapper"><span class="anchor-icon" pointing-to="-1039470044%2FClasslikes%2F-1397293861"></span>
|
|
<div class="copy-popup-wrapper "><span class="copy-popup-icon"></span><span>Link copied to clipboard</span></div>
|
|
</span></span></div>
|
|
<div>
|
|
<div class="title">
|
|
<div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-depenent-content" data-active="" data-togglable=":kompendium-core:dokkaHtmlPartial/main"><div class="symbol monospace"><span class="token keyword">class </span><a href="-kompendium/index.html">Kompendium</a><span class="token punctuation">(</span>config<span class="token operator">: </span><a href="-kompendium/-configuration/index.html">Kompendium.Configuration</a><span class="token punctuation">)</span><span class="top-right-position"><span class="copy-icon"></span><div class="copy-popup-wrapper popup-to-left"><span class="copy-popup-icon"></span><span>Content copied to clipboard</span></div></span></div></div></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<a data-name="-204668373%2FClasslikes%2F-1397293861" anchor-label="KompendiumPreFlight" id="-204668373%2FClasslikes%2F-1397293861" data-filterable-set=":kompendium-core:dokkaHtmlPartial/main"></a>
|
|
<div class="table-row" data-filterable-current=":kompendium-core:dokkaHtmlPartial/main" data-filterable-set=":kompendium-core:dokkaHtmlPartial/main">
|
|
<div class="main-subrow keyValue ">
|
|
<div class=""><span class="inline-flex">
|
|
<div><a href="-kompendium-pre-flight/index.html"><span>Kompendium</span><wbr><span>Pre</span><wbr><span><span>Flight</span></span></a></div>
|
|
<span class="anchor-wrapper"><span class="anchor-icon" pointing-to="-204668373%2FClasslikes%2F-1397293861"></span>
|
|
<div class="copy-popup-wrapper "><span class="copy-popup-icon"></span><span>Link copied to clipboard</span></div>
|
|
</span></span></div>
|
|
<div>
|
|
<div class="title">
|
|
<div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-depenent-content" data-active="" data-togglable=":kompendium-core:dokkaHtmlPartial/main"><div class="symbol monospace"><span class="token keyword">object </span><a href="-kompendium-pre-flight/index.html">KompendiumPreFlight</a><span class="top-right-position"><span class="copy-icon"></span><div class="copy-popup-wrapper popup-to-left"><span class="copy-popup-icon"></span><span>Content copied to clipboard</span></div></span></div><div class="brief "><p class="paragraph">Functions are considered preflight when they are used to intercept a method ahead of running.</p></div></div></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<a data-name="826197168%2FClasslikes%2F-1397293861" anchor-label="Kontent" id="826197168%2FClasslikes%2F-1397293861" data-filterable-set=":kompendium-core:dokkaHtmlPartial/main"></a>
|
|
<div class="table-row" data-filterable-current=":kompendium-core:dokkaHtmlPartial/main" data-filterable-set=":kompendium-core:dokkaHtmlPartial/main">
|
|
<div class="main-subrow keyValue ">
|
|
<div class=""><span class="inline-flex">
|
|
<div><a href="-kontent/index.html"><span><span>Kontent</span></span></a></div>
|
|
<span class="anchor-wrapper"><span class="anchor-icon" pointing-to="826197168%2FClasslikes%2F-1397293861"></span>
|
|
<div class="copy-popup-wrapper "><span class="copy-popup-icon"></span><span>Link copied to clipboard</span></div>
|
|
</span></span></div>
|
|
<div>
|
|
<div class="title">
|
|
<div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-depenent-content" data-active="" data-togglable=":kompendium-core:dokkaHtmlPartial/main"><div class="symbol monospace"><span class="token keyword">object </span><a href="-kontent/index.html">Kontent</a><span class="top-right-position"><span class="copy-icon"></span><div class="copy-popup-wrapper popup-to-left"><span class="copy-popup-icon"></span><span>Content copied to clipboard</span></div></span></div><div class="brief "><p class="paragraph">Responsible for generating the schema map that is used to power all object references across the API Spec.</p></div></div></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<a data-name="1041404093%2FClasslikes%2F-1397293861" anchor-label="Notarized" id="1041404093%2FClasslikes%2F-1397293861" data-filterable-set=":kompendium-core:dokkaHtmlPartial/main"></a>
|
|
<div class="table-row" data-filterable-current=":kompendium-core:dokkaHtmlPartial/main" data-filterable-set=":kompendium-core:dokkaHtmlPartial/main">
|
|
<div class="main-subrow keyValue ">
|
|
<div class=""><span class="inline-flex">
|
|
<div><a href="-notarized/index.html"><span><span>Notarized</span></span></a></div>
|
|
<span class="anchor-wrapper"><span class="anchor-icon" pointing-to="1041404093%2FClasslikes%2F-1397293861"></span>
|
|
<div class="copy-popup-wrapper "><span class="copy-popup-icon"></span><span>Link copied to clipboard</span></div>
|
|
</span></span></div>
|
|
<div>
|
|
<div class="title">
|
|
<div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-depenent-content" data-active="" data-togglable=":kompendium-core:dokkaHtmlPartial/main"><div class="symbol monospace"><span class="token keyword">object </span><a href="-notarized/index.html">Notarized</a><span class="top-right-position"><span class="copy-icon"></span><div class="copy-popup-wrapper popup-to-left"><span class="copy-popup-icon"></span><span>Content copied to clipboard</span></div></span></div><div class="brief "><p class="paragraph">Notarization methods are the primary way that a Ktor API using Kompendium differentiates from a default Ktor application. On instantiation, a notarized route, provided with the proper metadata, will reflectively analyze all pertinent data to build a corresponding OpenAPI entry.</p></div></div></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="footer"><span class="go-to-top-icon"><a href="#content" id="go-to-top-link"></a></span><span>© 2022 Copyright</span><span class="pull-right"><span>Generated by </span><a href="https://github.com/Kotlin/dokka"><span>dokka</span><span class="padded-icon"></span></a></span></div>
|
|
</div>
|
|
</div>
|
|
|
|
</body></html>
|
|
|
|
|