For REST API's written in Go , you should take a quick look at github.com/go-fuego/fuego. Getting an OpenAPI-Spec & a SwaggerUI without any extra effort, is a huge win!

Having played a bit I'm now adding #OpenAPI docs with #Swagger UI to #Autonomi dweb using #utoipa and #utoipauto.

I'm neither a user nor, until now a builder of HTTP APIs so stumbling around, but these crates do a decent job of being usable even to a novice.

I really shouldn't be let loose with all this

Unlock the Power of Your APIs: A Hands-On Introduction to Quarkus OpenAPI with Swagger
Effortless API Documentation in Quarkus: Getting Started with OpenAPI
https://open.substack.com/pub/myfear/p/unlock-the-power-of-your-apis-a-hands
#Quarkus #Java #OpenAPI #Swagger #API

I’ve recently taken a closer look at the #Foursquare #API (updating the long unmaintained Platypush plugin, details on why coming soon).

At first their new API versioning schema seemed a bit confusing (why would anyone use arbitrary YYYYMMDD strings as versions?), but a closer look at how they implemented it revealed a quite clever design decision:

Versioning is controlled by the v parameter, which is a date that represents the “version” of the API for which you expect from Foursquare. It is designed to give developers the freedom to adapt to Foursquare API changes on their own schedule. The value of the v parameter is a date in YYYYMMDD format that lets you tell us “I’m prepared for API changes up to this date.”

You know when you look at an engineering decision that is so elegant and obvious that you think “damn, how could nobody think of this before?”

Nearly two decades spent managing /v1, /v2, /v2.5, /v2.almost3, /v3, managing migrations and deprecations, documenting breaking changes, introducing exponentially thicker layers of schemas and converters, and the obvious solution was just there under our nose.

Why don’t you just start with defining the base schemas of your API objects at the time of their first release, and then every time you add, modify or delete a field, or change some return type, or add a value to an enum, you just version the change with a timestamp?

Let the developer say “I understand the language that your API spoke 3 months ago”, and you just dynamically create the schemas, GraphQL or ORM snippets to parse requests and responses as of that date.

No more breaking changes. No more forced migrations. No more boilerplate to explicitly convert payloads across different API versions.

You construct the response by first applying the base schema, and then gradually patching it - just like you would do with a git rebase, or an ORM migration tool.

A downside may probably be that you can never really delete a column from the db if it was ever used by any version of your API.

And a challenge may also be to adapt tools like #OpenAPI / #Swagger that were designed around static schemas to also work with “dynamically versioned” selections.

But to me the problems it solves far outweight the downsides.

https://docs.foursquare.com/developer/reference/versioning

May we have a show of hands for this #TuneTuesday ? #ShowUsYourHands

Hand Back Down #TheDevilMakesThree

https://song.link/nl/i/1536247377

TIL that, if you push an #OpenAPI YAML spec file to a #GitLab repository, you get the full, *interactive* #Swagger UI rendered in the web preview

Is my understanding correct that with ASP.NET Core Web API minimal API's, you can't use Swagger in an easy way? No attributes. You'll have to manually create all the OpenAPI objects in order to add documentation on your input and output parameters?
#DotNet #ASPNETCore #Swagger #OpenAPI

Now we no longer live in a close we get to see yer actual people walking by sometimes. One of my fave Glasgow specific people watching pleasures is spotting people who walk with a bit of swagger.
This seems to be very Glasgow specific or at least the incidence is higher.
Some men look like they're setting off on their own personal Richard Ashcroft Bittersweet Symphony type walk journey.

#swagger https://vanramblings.com/vanpoli-ken-sim-swagger-bullying-misogyny-hubris-pt-1/