Include OpenAPIKit in the official and recommended SSWG projects.
OpenAPI is a broadly used specification for writing API documentation. OpenAPI documents can be used to generate interactive documentation, automate testing, generate code, or just provide a solid source of truth and a contract between a client and a server.
As linked above, a lot of great tooling already exists around the OpenAPI specification. The aforementioned code generator even supports Swift with improvements being actively discussed.
OpenAPIKit fits into the existing ecosystem as a relatively low level library, with the intention of supporting other libraries and tools on top of it. It currently captures nearly all of the specification in Swift
Codable types. Thanks to Swift's type system, OpenAPIKit validates OpenAPI documentation simply by decoding it and it guarantees that OpenAPI documentation it encodes meets the spec as well.
In short, OpenAPIKit is a foundation for any Swift code that aims to read or write OpenAPI documentation. My hope is that this spec implementation saves time for others interested in writing tooling or frameworks with a higher level of abstraction.
The OpenAPIKit library currently implements approximately 90% of the OpenAPI specification with approximately 95% test coverage. This includes substantial support for OpenAPI schemas, which are themselves close relatives of the very comprehensive JSON Schema specification. [EDIT 2/9/2020] ~95% completion with 98% test coverage.
The plan is to prioritize the following.
99% Spec Implementation
The first order of business is completing the implementation of the spec. To be perfectly honest, there are a few small things with particularly large time commitments attached that I will likely leave for later, perhaps needing to be motivated by request.
Decoding Error Legibility
This is a new addition, thanks to the comments from @lassejansen below.
The error output from failed attempts at decoding OpenAPI documents is currently often a bit of a mess. There is a lot that can be done, much of it without too much work, to improve that situation. Seeing as how reading JSON/YAML representations of OpenAPI documentation is a primary focus of this library, good error output should be a primary focus as well.
Canonical API Information
OpenAPI allows for an author to document the same API in numerous different ways. This flexibility can save time and offer convenience when authoring, but as someone consuming the documentation in order to transform it or analyze it somehow it can be cumbersome.
Easy examples of this flexibility include (1) the ability to define available servers at the top level of the document but also refine or add servers in the Path Items object and (2) the ability to define parameters in the Path Items object but also add them in the Operations object. OpenAPIKit should provide easy answers to questions like "what are all of the parameters for a given endpoint?" or "what is the full list of servers used by this API?"
Protocols to facilitate generating OpenAPI
I have begun to hone in on a set of protocols (and conformances for fundamental and standard library Swift types) to facilitate generation of OpenAPI schemas from arbitrary swift code. In addition, OpenAPIKit already provides a method for generating OpenAPI schemas from arbitrary swift types using reflection (this is the foundation on which response schemas are built for the Vapor example use-case below).
Neither of the first two examples are trivial as-is, but they would have been drastically larger undertakings without a Swift implementation of the OpenAPI spec on top of which to build.
Vapor API documentation generation
For those interested, I've created a proof of concept library and app using Vapor that takes advantage of OpenAPIKit to generate OpenAPI documentation from the same route code that serves up responses (granted, to truly take advantage of OpenAPI I needed to introduce some type information to the routes that Vapor does not require out-of-box).
JSON:API schema generation
Another example use-case of OpenAPIKit is this library -- it takes JSON:API types and generates OpenAPI schemas for them.
Personal side note: Perhaps ironically, I am a much bigger proponent of writing OpenAPI documentation first and then creating (or generating) endpoints that meet the spec. However, for small projects especially, it can be incredibly valuable to generate API documentation from the code instead of the other way around.
Writing OpenAPI documentation
Handwriting OpenAPI documentation may sound laborious, but I am actually not the least bit opposed to doing so in the right context -- in fact, I have written NodeJS tooling in the past to facilitate easy, repeatable, standardized OpenAPI documentation as part of contract driven API development. It's actually quite nice to write OpenAPI documentation using OpenAPIKit -- the declarative structure is reminiscent of YAML but you get type safety, declared constants without
$refs, and reusability a la Swift.
This is a late addition (1/27/2020).
I threw together an example of using OpenAPIKit in a scripting environment to create tooling to help facilitate writing OpenAPI documentation. This is the kind of script I have written in NodeJS in the past to allow my team to create consistent APIs with consistent documentation. In addition to being a simple example script, keep in mind the intention in this context is not to fully formulate the OpenAPI documentation within Swift -- this kind of script populates a YAML file with templates that the user of the script would then go and fill out.