Skip to content

Commit

Permalink
Generate documentation (#28)
Browse files Browse the repository at this point in the history
  • Loading branch information
@djones6
djones6 authored Aug 13, 2019
1 parent b9a5beb commit f8cffe1
Show file tree
Hide file tree
Showing 43 changed files with 6,659 additions and 6 deletions.
2 changes: 1 addition & 1 deletion .jazzy.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,4 @@ readme: README.md
skip_undocumented: false
hide_documentation_coverage: false

xcodebuild_arguments: [-project, Kitura-OpenAPI.xcodeproj, -target, KituraOpenAPI, LIBRARY_SEARCH_PATHS=.build/debug]
xcodebuild_arguments: [-project, KituraOpenAPI.xcodeproj, -target, KituraOpenAPI, LIBRARY_SEARCH_PATHS=.build/debug]
4 changes: 2 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,9 +74,9 @@ You can easily write the OpenAPI definition for your Kitura router to a file:
try KituraOpenAPI.writeOpenAPI(from: router, to: "/myProject/kitura-server.json")
```

## More information
## Limitations

Kitura-OpenAPI works by using Kitura's ability to introspect the registered Codable routes at runtime. This feature was added in Kitura 2.4. Hence, if you are not using Codable routing you unfortunately cannot take advantage of this feature. This is because only Codable routes provide the strong type information required in order to generate an OpenAPI definition at runtime.
Kitura-OpenAPI works by using Kitura's ability to introspect the registered Codable routes at runtime, a feature added in Kitura 2.4. Because Codable routes provide the strong type information required in order to generate an OpenAPI definition at runtime, this feature unfortunately cannot currently support 'raw' routes.

## Community

Expand Down
23 changes: 23 additions & 0 deletions Sources/KituraOpenAPI/KituraOpenAPI.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,29 @@ import Kitura
import LoggerAPI
import Foundation

/// KituraOpenAPI contains helper functions for the addition of endpoints to a Kitura `Router`
/// for serving:
/// - an OpenAPI definition of its routes and their associated data types,
/// - the [SwaggerUI](https://swagger.io/tools/swagger-ui/) tool, that allows exploration and
/// testing of the API via a web browser.
///
/// Usage Example:
///
/// ```swift
/// import Kitura
/// import KituraOpenAPI
///
/// let router = Router()
/// KituraOpenAPI.addEndpoints(to: router) // Register default endpoints
/// ```
///
/// The endpoints have default values defined by the `defaultConfig` property. You can customize
/// the endpoints by supplying a `KituraOpenAPIConfig`:
///
/// ```swift
/// let config = KituraOpenAPIConfig(apiPath: "/swagger", swaggerUIPath: "/swagger/ui")
/// KituraOpenAPI.addEndpoints(to: router, with: config)
/// ```
public class KituraOpenAPI {
/// The default endpoints registered by `KituraOpenAPI.addEndpoints` to serve the
/// OpenAPI definition and the SwaggerUI tool. These values are `/openapi` and
Expand Down
10 changes: 7 additions & 3 deletions Sources/KituraOpenAPI/KituraOpenAPIConfig.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,18 @@
* limitations under the License.
*/

/// Defines the endpoints for the OpenAPI document and SwaggerUI tool when used
/// in conjunction with `KituraOpenAPI.addEndpoints(to:with:)`.
public struct KituraOpenAPIConfig {
// Path to serve OpenAPI specification from. If nil, do not serve.
/// Path to serve OpenAPI specification from. If nil, do not serve.
public let apiPath: String?

// Path to serve SwaggerUI from. If nil, do not serve.
/// Path to serve SwaggerUI from. If nil, do not serve.
public let swaggerUIPath: String?

// Create KituraOpenAPIConfig
/// Create a `KituraOpenAPIConfig` with custom endpoints.
/// - Parameter apiPath: Path to serve OpenAPI specification from. If nil, do not serve.
/// - Parameter swaggerUIPath: Path to serve SwaggerUI from. If nil, do not serve.
public init(apiPath: String?, swaggerUIPath: String?) {
self.apiPath = apiPath
self.swaggerUIPath = swaggerUIPath
Expand Down
147 changes: 147 additions & 0 deletions docs/Classes.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,147 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Classes Reference</title>
<link rel="stylesheet" type="text/css" href="css/jazzy.css" />
<link rel="stylesheet" type="text/css" href="css/highlight.css" />
<meta charset="utf-8">
<script src="js/jquery.min.js" defer></script>
<script src="js/jazzy.js" defer></script>

<script src="js/lunr.min.js" defer></script>
<script src="js/typeahead.jquery.js" defer></script>
<script src="js/jazzy.search.js" defer></script>
</head>
<body>

<a name="//apple_ref/swift/Section/Classes" class="dashAnchor"></a>

<a title="Classes Reference"></a>

<header class="header">
<p class="header-col header-col--primary">
<a class="header-link" href="index.html">
KituraOpenAPI Docs
</a>
(100% documented)
</p>

<p class="header-col--secondary">
<form role="search" action="search.json">
<input type="text" placeholder="Search documentation" data-typeahead>
</form>
</p>

<p class="header-col header-col--secondary">
<a class="header-link" href="https://github.com/IBM-Swift/Kitura-OpenAPI">
<img class="header-icon" src="img/gh.png"/>
View on GitHub
</a>
</p>

</header>

<p class="breadcrumbs">
<a class="breadcrumb" href="index.html">KituraOpenAPI Reference</a>
<img class="carat" src="img/carat.png" />
Classes Reference
</p>

<div class="content-wrapper">
<nav class="navigation">
<ul class="nav-groups">
<li class="nav-group-name">
<a class="nav-group-name-link" href="Classes.html">Classes</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a class="nav-group-task-link" href="Classes/KituraOpenAPI.html">KituraOpenAPI</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a class="nav-group-name-link" href="Structs.html">Structures</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a class="nav-group-task-link" href="Structs/KituraOpenAPIConfig.html">KituraOpenAPIConfig</a>
</li>
</ul>
</li>
</ul>
</nav>
<article class="main-content">

<section class="section">
<div class="section-content">
<h1>Classes</h1>
<p>The following classes are available globally.</p>

</div>
</section>

<section class="section">
<div class="section-content">
<div class="task-group">
<ul class="item-container">
<li class="item">
<div>
<code>
<a name="/s:13KituraOpenAPIAAC"></a>
<a name="//apple_ref/swift/Class/KituraOpenAPI" class="dashAnchor"></a>
<a class="token" href="#/s:13KituraOpenAPIAAC">KituraOpenAPI</a>
</code>
</div>
<div class="height-container">
<div class="pointer-container"></div>
<section class="section">
<div class="pointer"></div>
<div class="abstract">
<p>KituraOpenAPI contains helper functions for the addition of endpoints to a Kitura <code>Router</code>
for serving:</p>

<ul>
<li>an OpenAPI definition of its routes and their associated data types,</li>
<li>the <a href="https://swagger.io/tools/swagger-ui/">SwaggerUI</a> tool, that allows exploration and
testing of the API via a web browser.</li>
</ul>

<p>Usage Example:</p>
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">Kitura</span>
<span class="kd">import</span> <span class="kt">KituraOpenAPI</span>

<span class="k">let</span> <span class="nv">router</span> <span class="o">=</span> <span class="kt">Router</span><span class="p">()</span>
<span class="kt">KituraOpenAPI</span><span class="o">.</span><span class="nf">addEndpoints</span><span class="p">(</span><span class="nv">to</span><span class="p">:</span> <span class="n">router</span><span class="p">)</span> <span class="c1">// Register default endpoints</span>
</code></pre>

<p>The endpoints have default values defined by the <code>defaultConfig</code> property. You can customize
the endpoints by supplying a <code><a href="Structs/KituraOpenAPIConfig.html">KituraOpenAPIConfig</a></code>:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">config</span> <span class="o">=</span> <span class="kt">KituraOpenAPIConfig</span><span class="p">(</span><span class="nv">apiPath</span><span class="p">:</span> <span class="s">"/swagger"</span><span class="p">,</span> <span class="nv">swaggerUIPath</span><span class="p">:</span> <span class="s">"/swagger/ui"</span><span class="p">)</span>
<span class="kt">KituraOpenAPI</span><span class="o">.</span><span class="nf">addEndpoints</span><span class="p">(</span><span class="nv">to</span><span class="p">:</span> <span class="n">router</span><span class="p">,</span> <span class="nv">with</span><span class="p">:</span> <span class="n">config</span><span class="p">)</span>
</code></pre>

<a href="Classes/KituraOpenAPI.html" class="slightly-smaller">See more</a>
</div>
<div class="declaration">
<h4>Declaration</h4>
<div class="language">
<p class="aside-title">Swift</p>
<pre class="highlight swift"><code><span class="kd">public</span> <span class="kd">class</span> <span class="kt">KituraOpenAPI</span></code></pre>

</div>
</div>
</section>
</div>
</li>
</ul>
</div>
</div>
</section>

</article>
</div>
<section class="footer">
<p>&copy; 2019 <a class="link" href="" target="_blank" rel="external">IBM</a>. All rights reserved. (Last updated: 2019-08-13)</p>
<p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.9.6</a>, a <a class="link" href="https://realm.io" target="_blank" rel="external">Realm</a> project.</p>
</section>
</body>
</div>
</html>
Loading

0 comments on commit f8cffe1

Please sign in to comment.