标签：#openapi

Nim doesn't have a lot of options for building HTTP APIs with the kind of batteries-included developer experience you get in frameworks like FastAPI or Express with Swagger middleware. mummy is a fast, solid HTTP/WebSocket server library for Nim (my fork with the additions below is at github.com/isaiahpeter/mummy ) — but out of the box, it doesn't generate OpenAPI specs, validate request bodies, or give you typed path parameters. So I forked it and added those. This post walks through what I built, why, and what I learned extending an existing Nim library instead of starting from scratch. Why mummy, and why OpenAPI I wanted a Nim backend for a few projects (a contact-form API, a todo API demo) and kept missing three things I'd take for granted in other ecosystems: Auto-generated API docs — a /docs endpoint you can actually hand to someone, generated from your routes instead of hand-written. Typed path parameters — pulling id out of /users/{id} as an int without manual parsing and error handling in every handler. Request validation — rejecting a bad JSON body before it reaches your handler logic, with a schema to back it up. mummy is fast and minimal by design, which is exactly why it was worth extending rather than replacing. What I added OpenAPI spec generation. I added openapi_schema.nim and openapi_router.nim , which let you wrap routes in an OpenApiRouter and attach a summary, tags, and a response schema via schemaOf . The router serves both /openapi.json and a browsable /docs page generated from your actual route definitions — so the docs can't drift out of sync with the code the way hand-written API docs do. Typed path parameters. pathParam[T](request, "id") pulls a path segment and parses it as the type you ask for, with a clean 400 response if parsing fails. One gotcha worth flagging if you try this yourself: in this Nim version, the generic dot-call form ( request.pathParam[int]("id") ) doesn't parse — you have to call it as pathParam[int](request, "id") in

Originally published at mendapi.com . Between two published snapshots of the Cloudflare OpenAPI schema — 7abe88500e55 (2026-03-31) → c92b9b0fde23 (2026-07-27) — a raw structural diff produced 6,354 change records. 136 of them were endpoint path removals, the scariest kind a diff can report: the route your code calls is simply gone from the spec. Except 119 of those 136 were not gone at all. This is the accounting of how we know, per record, with machine evidence. The trap in a raw diff A path removal in a spec diff means one thing: the string key disappeared from the paths object. It does not mean the runtime URL stopped working. Specs get refactored — concrete routes collapse into templated ones, path parameters get renamed, methods get merged — and every one of those refactors shows up as a "removal" if you only look at one side of the diff. An alerting tool that pages you 136 times for this corridor is training you to ignore it. The whole job of the curation layer is to keep that from happening without silently dropping a real break. The ledger: 17 + 119 = 136 Every one of the 136 raw removals has an adjudicated destination. 17 were kept as genuinely client-breaking: the runtime URL or method really disappeared, with no surviving successor. The other 119 were excluded, each with machine evidence from the two spec snapshots that the surface actually survives: Template consolidation — 107 records. Concrete Workers AI model routes like /ai/run/@cf/baai/bge-m3 collapsed into the pre-existing generic /ai/run/{model_name} route. The runtime URL a client sends never changed; the spec just stopped enumerating each model. The evidence rule requires the templated route to exist in both snapshots and to swallow the removed path with a literal-anchored match, so a template that is merely a shape prefix of a genuinely removed endpoint does not count. Parameter rename, runtime-identical — 11 records. Path parameters renamed ( {postfix_id} to {investigate_id} and friends). Afte

If you're writing Playwright API tests manually from an OpenAPI/Swagger spec, you're doing work that should be automated. Every endpoint in your spec already tells you: What the request looks like (path, method, parameters, body schema) What responses to expect (200, 401, 404, 422...) What fields are required What security is needed That's not documentation — it's a test plan. You're just not running it yet. What I built I got tired of the boilerplate loop: read spec → write happy path → add 401 test → add missing-field test → repeat for 40 endpoints. So I built a tool that does it for you. swagger-to-playwright.vercel.app takes your OpenAPI 3.x spec (YAML or JSON) and generates a ready-to-run Playwright .spec.ts file. For each endpoint, it produces four tests: 1. Happy path — calls the endpoint with valid data, asserts 2xx response and key fields in the body. 2. Auth check — if your spec declares a security scheme, it calls without a token and asserts 401. Only generated when the spec actually says authentication is required — no false positives. 3. Input validation — sends a request with missing required fields (or wrong types, invalid enums) and asserts 422. Reads directly from your schema's required array and field types. 4. Contract validation — if there's a path parameter, it calls with an invalid value and asserts 404. What the output looks like Here's what you get for a POST /users endpoint with email and password required: import { test , expect } from ' @playwright/test ' ; test . describe ( ' POST /users ' , () => { test ( ' happy path — creates user successfully ' , async ({ request }) => { const res = await request . post ( ' /users ' , { data : { email : ' test@example.com ' , password : ' password123 ' } }); expect ( res . status ()). toBe ( 201 ); const body = await res . json (); expect ( body ). toHaveProperty ( ' id ' ); }); test ( ' auth — 401 without token ' , async ({ request }) => { const res = await request . post ( ' /users ' , { headers : {

TL;DR — We'll install dskripchenko/laravel-api , write one controller, and end up with a versioned API ( /api/v1/... ) and interactive OpenAPI 3.0 docs at /api/doc — generated from the docblock you'd write anyway. Then we'll ship a v2 without copy-pasting a single controller. The problem Two things rot in every growing Laravel API: Versioning. v1 ships, then v2 needs to change three endpoints but keep the other twenty. You either copy-paste a V2 folder (and now bugfixes live in two places) or bolt if ($version === 2) branches into your controllers. Docs. The OpenAPI spec drifts from the code the moment you merge. Annotation libraries ( #[OA\Get(...)] , giant YAML files) ask you to describe your API twice — once in code, once in attributes. This package's bet: your controller already describes itself . The method name, the request fields, the response shape — write them once, as a normal PHPDoc, and let the package derive routes and docs from it. Versioning becomes plain PHP inheritance. Let's build it. What we'll build A tiny tasks API: POST /api/v1/task/list — list tasks POST /api/v1/task/create — create one interactive docs at GET /api/doc (raw spec per version at /api/doc/{version} ) then a v2 that adds an endpoint without touching v1 Total: ~4 small files. Step 0 — Install composer require dskripchenko/laravel-api Publish the config (optional, but handy to see the knobs): php artisan vendor:publish --tag = laravel-api-config // config/laravel-api.php return [ 'prefix' => 'api' , // → /api/... 'uri_pattern' => '{version}/{controller}/{action}' , 'available_methods' => [ 'get' , 'post' , 'put' , 'patch' , 'delete' ], 'openapi_path' => 'public/openapi' , 'doc_middleware' => [], // lock down /api/doc here ]; Step 1 — Write a controller Nothing exotic — it extends the package's ApiController , which gives you response helpers ( success() , error() , validationError() , created() , noContent() , notFound() ). The docblock is the documentation : <?php namespace App\Api

Most apps don't just call one API endpoint. They call a whole chain of them. For example, you might log in, get a token, and then pass that token to another service. Tracking these multi-step chains can get messy quickly. To help fix this, the OpenAPI Initiative created the Arazzo Specification . It gives us a standard way to link different endpoints into clear workflows. But writing these workflow files by hand in a regular text editor is tough. It is very easy to lose track of how data moves from one step to the next. That is why I built Arazzo Visualizer for VS Code. It is a free, open-source extension that makes the Arazzo spec visual and easy to use. Live Interactive Graphs The extension reads your workflow files and turns them into interactive maps on the fly. See Data Flow: Look at exactly how data moves between steps. Catch Errors Early: Spot broken paths before you even run your code. Clean Layouts: Navigate large workflows without getting lost in thousands of lines of text. Built-In Workflow Runner Seeing the map is great, but testing it is even better. The tool has a step-by-step runner built right into your editor. Run a single step or execute the whole chain. See real-time data payloads and HTTP headers. Watch requests happen live to pinpoint bugs fast. Give it a Try The project is fully open source, and you can grab it or check out the code using the links below: Download: Install it directly from the VS Code Marketplace . Source Code: Check out the repository, report bugs, or contribute on GitHub . Deep Dive: Read my full technical breakdown and design on Medium . If you are working with API chains, I would love for you to try it out. Drop your feedback in the comments below! Note: Arazzo v1.1.0 is out with official AsyncAPI support. I am currently updating the VS Code extension to support these new features. Stay tuned for future updates!

It is straightforward to configure a minimal API to produce an OpenAPI document at build time . This runs the API during build, requests the OpenAPI document from it, and saves it to disk. The slightly trickier part is to put checks in Program.cs to exclude any startup code that cannot run at build time. This is typically done because configuration key/value pairs are not available at that time. For example: if (! isBuildTime ) { connString = builder . Configuration . GetConnectionString ( "AppDB" ) ?? throw new InvalidOperationException ( "Connection string 'AppDB' is not configured." ); builder . Services . AddDbContext < AppDbContext >( options => { options . UseNpgsql ( connString ); } ); } The question is how to deduce that the API has been launched at build time, i.e. isBuildTime should be true? The official way of doing this is to check that the assembly that invoked the API is "GetDocument.Insider" : var isBuildTime = Assembly . GetEntryAssembly ()?. GetName (). Name == "GetDocument.Insider" ; GetDocument.Insider.dll is the command line tool that automatically runs during build of the API if the .csproj includes the following reference: <PackageReference Include= "Microsoft.Extensions.ApiDescription.Server" Version= "10.0.7" > ... </PackageReference> This package is a shim. It only provides build targets and props and hooks into the build of the API to run the command-line tool dotnet-getdocument . This tool in turn runs the command line tool GetDocument.Insider that we check for. This is a pretty convoluted sequence: Microsoft.Extensions.ApiDescription.Server provides targets that run during build of the API. One of those targets runs the command line tool dotnet-getdocument That in turn runs the command line tool GetDocument.Insider That in turn runs the API and fetches the /openapi/v1/json (or other configured endpoint) to get the OpenAPI document and saves it to disk. Checking in Program.cs if the API was invoked by the assembly GetDocument.Insider.dll t