Open API Tools & Swift - Personal Experience

Server Pitches
1

This post is meant to illustrate the current state of tooling for Server Side Swift projects written from the perspective of someone who is still very new to Swift, and is probably making some assumptions that may prove to be incorrect.

I recently began a personal project in which I wanted to use Kubernetes (K8s) & Swift. To get started I created a library that was going to house all the K8s types, and the HTTP Client for communicating with the K8s API. With the goal of importing this library into all the other projects I had planned. Lucky enough for me, K8s uses the OpenAPI Spec, so generating the client code should be easy. I was mistaken, for Swift that is not the case. Specifically for any Swift client that you wanted to run on Linux. At the time of writing this, there did not exist a Swift Client that the Open-API code generation tool could generate that could be ran on Linux. I had concluded, with the help of others, that if I wanted a Pure-Swift Kubernetes library that could be ran on Linux, I would have to write the HTTP Client code myself.

Project: https://github.com/spprichard/Swifternetes
This project is still in the very early stages, and I am still learning Swift.

All is not lost however, the Open-Api generator could generate the model code for the entire K8s API, which is a big win! What I mean by model code is, that the Request/Response types, all the Resource types (Pod, Deployment, Service, etc). There is a bit of a down side here too, the latest version of the Open-Api Generator for Swift is 4.2. At face value this seems like a minor issue to me because the library I was building was targeted for Swift 5.0 and later. I don’t think there would be any breaking changes in 4.2 to 5.0 in this case, but something to note.

I also noticed a lack of Codable support. It was not clear to me how I could get Codable support fo the the types the generator would generate without having basically write the types myself. Which defeats the purpose of the Open-Api Code Generator all together.

As it stands today, the Swifternetes project is off the ground, if even by an inch! Along the way I have learned a lot, and hopefully will consider to do so. The reason for this post is to discuss my experiences trying to build this library, and possible areas of focus for the Server Working Group in 2020

Tools I used:

Areas of Potential Interest

  • Give the Open-Api Code Generator for Swift that ability to produce clients that can be compiled and ran on Linux.
  • Add support for the new AsyncHTTPClient as one of the client the Open-Api Code generator can generate.
  • Update the Open-Api Code Generator for Swift to 5.0 and later
  • Give the Open-Api Code Generator for Swift the ability to generate models that conform to Codable

I look forward to the discussion to follow!

6 Likes
2

@spprichard I started an oas project for a vapor 4 server. It uses Codables. As I ramp up my vapor project, I’ll put together a Codegen for the AsyncHTTPClient as well.

I would love to get your opinion on the vapor 4 Codegen if you get a chance. I am actively working on it and addressing issues as I run into them.

2 Likes
3

@thecheatah Yea I looked at that this weekend. I'm for sure interested in it.

So for my specific case, I used this project GitHub - kubernetes-client/gen: Common generator scripts for all client libraries to generate the Swift code for my Switernetes project. However, it looks to use a swagger.json? I'm really not sure how swagger and Open-Api play together. If any one has knowledge on this I'm all ears. Would your tool be able to take a swagger.json? The examples I see look to use a .yaml file.

4

openAPI is the evolution of what started as swagger, so there might be some tweaking of some specifics, but it should handle it as long as it can read and understand earlier versions of the openAPI spec.

5

@spprichard I can try to reduce the confusion for you. Swagger went through rebranding exercise and version "3" of swagger was named OpenAPI Spec 3 (oas3). So it's swagger 1 (no-one really uses), swagger 2 and openapi spec 3.

The contents of the swagger or openapi spec can either be yaml or json. This online editor can convert between the two for you.

6

@Joseph_Heck & @thecheatah thanks for clearing that up!

@thecheatah I will for sure try your tool for my Swifternetes project. Having the AsyncHTTPClient option is exactly what I need for this project to take off. Can you keep me posted on the progress? Also, let me know if I can help in anyway

7

@thecheatah Do you know of a tool beside the online editor for converting JSON definitions to YAML? The online one not like the size of the Kubernetes spec.....Web page freezes

8

Take a look at this post. Looks like you can do it using Python on command line.

Google chrome might be your best bet with the online tool if you want to give that a go.

Also, I will let you know when I get started on the AsyncHTTPClient codegen.

1 Like
9

Fantastic! Will do

10

We've added a Swift 5 client generator (beta) to OpenAPI Generator. Please check it out and let us know if you've any feedback:

Ref: Reddit - Dive into anything

2 Likes
11

@spprichard would you consider contributing those files to the GitHub - kubernetes-client/gen: Common generator scripts for all client libraries repo itself?

12

Yea, I don't see why not. I'll try to do that this weekend

13

@wing328 That's awesome!

Correct me if I am wrong here, but URLSession doesn't compile for Linux?

14

URLSession used to have some difficulties on Linux in the very early days, but it works great now. The only concern with using URLSession is for non-blocking server apps where the different concurrency models could create performance bottlenecks. URLSession has also been moved to the FoundationNetworking module on Linux only (to avoid linking cURL everywhere) which can be a sharp edge for people.

1 Like
15

@tanner0101 Cool, that makes sense. Thank you.

So there is still a need to have a non-blocking library option for the OpenAPI Code Gen project?

16

Yeah I definitely think so. I think it should be available in addition to URLSession. For iOS use cases URLSession (or Alamofire) make a lot of sense. For server, especially in cases where non-blocking performance is critical, you will want AsyncHTTPClient.

It looks like openapi-generator has different files for Alamofire, URLSession, RxSwift, etc (https://github.com/OpenAPITools/openapi-generator/blob/master/bin/swift5-petstore-urlsession.json). Could we add AsyncHTTPClient support next to those?

1 Like
17

Definitely. We welcome contribution on that. Can you please open an issue/ticket via Sign in to GitHub · GitHub to track this?

1 Like
18

Here it is: Add Support for Swift's AsyncHTTPClient · Issue #4957 · OpenAPITools/openapi-generator · GitHub

Thanks!

2 Likes
19

SwagGen might be another tool worth exploring, which is itself written in Swift and uses Stencil templates GitHub - yonaskolb/SwagGen: OpenAPI/Swagger 3.0 Parser and Swift code generator

By default it generates client side code, but the templates are very customizable. The models also have built in Codable support

5 Likes
20

UPDATE: We've released OpenAPI Generator v4.2.3, which includes the Swift 5 client generator and many enhancements, bug fixes: https://twitter.com/oas_generator/status/1223289771813785601

5 Likes