Pkl library or package for defining openapi specs

[luistrigueiros]

Is there a Pkl library or package that if is constraint to allow crafting and defining openapi specs ?
As a configuration language Pkl allow us to represent any json/yml object graph, so my question is if I would like to author Openapi specs using Pkl is there a library that is already geared for this use case this ?
I go as far is there a formal away to translate any JSON schema into Pkl ?

Thank you, kindly
Luis Oscar

[kkivan]

looks like it
https://github.com/apple/pkl-pantry/tree/[email protected]/packages/org.openapis.v3

[luistrigueiros]

Hi Ivan is there are reference examples on how to use this package, I am still in the beginning of may learning journey. Thank you.

…

On Wed, Jul 3, 2024 at 9:33 AM Ivan Kvyatkovskiy ***@***.***> wrote: looks like it ***@***.***/packages/org.openapis.v3 — Reply to this email directly, view it on GitHub <#105 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAEQFZ4PTBP23WYA24VHCFLZKOZN5AVCNFSM6AAAAABDCWTJ6WVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4TSNBVGM4TI> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[giordano-newday]

I'm interested to any examples too. @bioball sorry to tag you directly, but some help here would be much appreciated

[HT154]

What sort of example are you looking for?

As with any Pkl module, you would typically amend it and start "filling it out" like a form. Something like this:

amends "package://pkg.pkl-lang.org/pkl-pantry/[email protected]#/Document.pkl"

servers {
  // ...
}

paths {
  // ...
}

components {
  // ...
}

The structure is exactly the same as a JSON/YAML OpenAPI spec, but using Pkl allows using the module's rich type information for validation of the spec, improved editor experience (in JetBrains IDEs currently, others once the LSP is released), and reducing repetition without having to always using fiddly refs.

If you have more specific questions I can try answering!

[giordano-newday]

Thanks, @HT154.

Would it be possible to create this module from an existing OpenAPI spec?

I'm currently implementing an API Gateway (APIGW) using Pkl as a configuration language. The requirements are for filtering endpoints and response properties, as well as performing simple property transformations such as 'renaming keys', 'type conversion', etc.

We've defined our config file as follows:

config {
  services {
     new endpoint {
         name: //..
         transformations: {
            //...
         }         
     }
  }
}

We read the configuration in our Spring Boot Kotlin app and apply the transformations to the JSON received: it works like a charm!

The next step is to expose the OpenAPI spec from our API Gateway so that clients can use it to generate their own clients. I'm looking for a way to generate the OpenAPI spec from the Pkl configuration file, perhaps by importing the OpenAPI spec and applying the transformations to it.

Something like this implementation: https://www.krakend.io/docs/enterprise/endpoints/openapi/.

Note that we are not implementing a commercial product, so we don't need anything overly sophisticated, but we would still like to keep it as simple and robust as possible.

Thank you for your help.

[HT154]

Generating the spec whole cloth and transforming an existing one are probably divergent enough approaches to discuss separately.

Transformation

The great news here is that Pkl has a (fairly) general mechanism for reading JSON/YAML data and converting it into existing Pkl types! The deepToTyped module in apple-pantry is a common way to do this. You can see an example of it in use here: https://github.com/apple/pkl-pantry/blob/[email protected]/packages/k8s.contrib.crd/generate.pkl#L112

For your usage, you would read an existing OpenAPI spec, parse it, and convert it to the Document type. Then, you would apply any transformations and render it back out as necessary.

As far as generating those transformations, an interesting way to do this might be to extend your endpoint class to be a Class-as-a-Function type with an output of type Mixin<Document>. Your spec transformation code would then apply each mixin in turn to the input spec.

Generation from scratch

To generate a spec from scratch, you might take a similar approach, but instead of using a Mixin, you might have each endpoint generate one or more OpenAPI Path. You would likely have a module that amends the OpenAPI Document imports your config module, and loops over your endpoints to produce the final spec. How this actually gets assembled into a full spec probably depends pretty heavily on the structure of your config system that hasn't been shared.

[giordano-newday]

That sounds good! Thanks, @HT154.
This very helpful. I'm thinking of doing a POC for both the methods and report here my result for feedback and future reference