About libopenapi

What is it and why does it exist?

---

If you’re looking for an OpenAPI library for golang, you’ve probably already discovered the excellent kin-openapi (which is great by the way).

Except, there is one problem with it, that means we can’t use it for our use-cases.

kin-openapi is lossy.

When parsing OpenAPI specifications at a low level, kin-openapi runs out of power when you need to know the original line numbers and columns and the original node data exposed.

All that data is lost when the OpenAPI specification is loaded in by kin-openapi. Mainly because the library will unmarshal data directly into structs, which works great - if you don’t need access to the original specification low level details.

We were unable to build openapi-changes using kin, all the data we needed was missing from the model.

Why not just modify kin-openapi?

It would require a complete and total re-build of the entire library, with a different design to expose the same functionality, a similar design to libopenapi would need to be employed, using custom marshaling and unmarshalling code, for every model.

libopenapi is lossless

libopenapi has been designed to retain all of that really low-level detail about the AST, line numbers, column numbers, comments, original AST structure - everything you could need.

libopenapi has a porcelain (high-level) and a plumbing (low-level) API. Every high level struct, has the ability to GoLow() and dive from the high-level model, down to the low-level model and look-up any detail about the underlying raw data backing that model.

This library exists because this very need existed inside a mega-corp. We built an internal version of libopenapi;

This library is the result of years of learning and battle testing OpenAPI in golang. This library represents what would have been created, if we knew then - what we know now.