By using Kitura-OpenAPI you can:
- Host an automatically generated OpenAPI definition of your application on a defined endpoint, for example
- Host the SwaggerUI tool on a defined endpoint, for example
Kitura-OpenAPI to the dependencies within your application's
Package.swift file. Substitute
"x.x.x" with the latest
.package(url: "https://github.com/IBM-Swift/Kitura-OpenAPI.git", from: "x.x.x")
KituraOpenAPI to your target's dependencies:
.target(name: "example", dependencies: ["KituraOpenAPI"]),
Import the package inside your application:
Inside your application, add a call to
KituraOpenAPI.addEndpoints(to:with:) during startup, passing through the Kitura
Router that you want to host the OpenAPI endpoints on. The
with parameter optionally allows you to configure where the endpoints are hosted.
KituraOpenAPI.addEndpoints(to: router) // Use the default endpoints
You can then visit
/openapi in a web browser to view the generated OpenAPI definition, and
/openapi/ui to view SwaggerUI.
If you wish, you can customize the endpoint paths:
let config = KituraOpenAPIConfig(apiPath: "/swagger", swaggerUIPath: "/swagger/ui") KituraOpenAPI.addEndpoints(to: router, with: config)
Writing OpenAPI definition to a file
You can easily write the OpenAPI definition for your Kitura router to a file:
try KituraOpenAPI.writeOpenAPI(from: router, to: "/myProject/kitura-server.json")
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.
We love to talk server-side Swift and Kitura. Join our Slack to meet the team!
This library is licensed under Apache 2.0. Full license text is available in LICENSE.
You may find interesting
1.4.0 - 2020-03-05 14:00:20
- Update to SwaggerUI 3.25.0 for compatibility with OpenAPI v3 (#29)
1.3.0 - 2019-08-13 12:22:48
- API to write the generated OpenAPI document to a file (#25)
- API documentation has been published to kitura.io
1.2.1 - 2019-04-05 10:47:40
- Build in Swift 5 mode
1.2.0 - 2019-02-13 11:42:55
- feat: Remove Stencil dependency (#19)
1.1.2 - 2019-01-24 11:44:54
1.1.1 - 2018-09-04 23:36:49
- Lower log level of two messages.
1.1.0 - 2018-08-31 16:02:33
- Update swaggerui to 3.18.0 (#9)
- Allow swaggerui to be served from custom path (#10)
1.0.3 - 2018-07-24 14:11:34
Fix SwaggerUI when deployed into cloud.
1.0.2 - 2018-06-08 08:35:37
1.0.1 - 2018-06-01 11:12:13
1.0.0 - 2018-06-01 10:05:25