How to start using OpenAPIKit

[CITMark]

Hi all,

So I've started this week on exploring server-side swift and one important thing always is documentation. So for other projects I normally saw swagger as a base. So I came across this framework that's also indexed by the SSWG, but I am now a bit confused on how to actually use this framework.

I saw two example projects somewhere in the readme. But one used a .yaml to generate the documentation and the other one was quite out-dated. I was wondering if some has a good example of an implementation of OpenAPIKit in a project. I was hoping that for example I could define the scheme per model that I have and some how attach this scheme to routes I've defined, same as you would do in for example TypeScript.

I am just wondering if someone as a very practical example / approach on how to start using this in the actual code base you are building your api in? I am already really happy if it shows how to do it for a simple model and how to actually show the documentation in for example a swagger page.

If I missed something where this is well explained, please link me to that place and ignore this QA.

Regards

Mark

A small follow up: I was wondering if there is a way to for example generate the .yaml based on the swift code and then serve this as a swagger documentation or something like that. I am still a bit new to this.

[mattpolzin]

I think your question is at least partially answered by saying that OpenAPIKit is intended to be pretty low-level. You aren't missing anything in the documentation if you come away thinking that OpenAPIKit is really just responsible for (a) parsing OpenAPI documents to Swift representations (using any decoder, likely JSON or YAML), (b) serializing Swift representations to OpenAPI Documents (using any encoder, likely JSON or YAML), and (c) validating OpenAPI and providing hopefully reasonable error messages when problems are found.

Given OpenAPIKit as a foundation, another library may provide semantic diffing of OpenAPI documents, generate JSON/YAML OpenAPI documentation from Swift source code, generate a documentation webpage from Vapor routes, or generate Swift code from JSON/YAML OpenAPI documentation.

Some of these are merely examples I put together rather than maintained projects; you may have already seen some of my Vapor examples, which are out of date from latest Vapor framework changes. My intention was to provide inspiration with those and I am not aware of more established projects doing similar things (yet). On the other hand, the Swift Package Registry docs example is production ready and maintained to the best of my knowledge and the CreateAPI framework is looking really good despite being a pretty new project!

---

I was hoping that for example I could define the scheme per model that I have and some how attach this scheme to routes I've defined, same as you would do in for example TypeScript.

Please let me know if I am missing the point here, as I am not familiar with the TypeScript comparison given, but perhaps the CreateAPI project is in line with this goal.

I am already really happy if it shows how to do it for a simple model and how to actually show the documentation in for example a swagger page.

I was wondering if there is a way to for example generate the .yaml based on the swift code and then serve this as a swagger documentation or something like that.

I think these are both addressed by what you might have been calling out as being an out-of-date example: Vapor OpenAPI example. This is definitely not up to date with latest Vapor changes, but it does serve as proof of concept for what you are describing. That is, it's definitely within reach, but unfortunately you might not find a walkthrough or example code that can be followed to-the-letter.

---

I do hope we see follow ups from others in the community in this discussion; I'd love to learn of other public-domain examples or new libraries that take OpenAPIKit and make it more applicable to the use-cases you are describing!