Rendering APIs & Schemas
Let’s be honest: writing the prose part of documentation is necessary, but it’s rarely the most interesting part of the job.
As a documentation author, your time is best spent perfecting the machine-readable schemas, not hand-crafting the surrounding text. That’s why this portal is built to maximise schema re-use — converting your technical schemas into human- and AI-facing documentation wherever possible, rather than asking you to duplicate that information as prose.
This saves you time, unlocks greater automation, and removes the risk of documentation drifting out of sync with the source of truth.
💡 The 80-20 rule
Spend most of your time getting your machine-readable schemas (OpenAPI, FinSpec, etc.) as complete and accurate as possible. With a solid schema as the foundation, the amount of surrounding text you need to write and maintain drops significantly.
Why not use an open-source library or plugin?
There are several open-source libraries that render OpenAPI documents. To save you searching for them, here are the most widely used:
- Swagger UI: perhaps the most mature and widespread OpenAPI rendering library.
- Redocly Redoc: modern OpenAPI rendering that links into a larger ecosystem.
- Docusaurus OpenAPI Plugin, which adds OpenAPI rendering to a Docusaurus site.
- OpenApi2Slate, which converts OpenAPI to Markdown for display in a Slate site.
- Scalar, which renders OpenAPI documents and can even generate SDKs.
These are all solid tools if REST is all you need to cover. The problem for trading firms is that none of them have any incentive to support FIX, SBE or proprietary trading protocols — that’s a niche far too small for a general-purpose OpenAPI tool to prioritise.
You could write a bespoke plugin for one of these platforms yourself, but then you own its ongoing maintenance, and you’re still limited by how well it can be made to fit a tool that wasn’t designed with FIX or binary protocols in mind. In practice, many firms end up hand-crafting parameter tables outside their codebase instead — information that then can’t be reused anywhere else.
Our focus is different: FIX and REST are first-class citizens here today, with the same tooling support. SBE and other financial protocols alongside WebSocket are on our roadmap, extending the same approach as we build them out.
Simply create a FinSpec file, point the portal to it, and you get:
- Beautifully rendered, searchable online documentation.
- A machine-readable API specification that’s well-structured and lintable.
- Auto-generated code for the popular QuickFIX, Artio and FerriumFIX engines.
- AI-ready documentation.
FAQs
Do I need to write FinSpec by hand? No — you can point the portal at an existing OpenAPI document for REST APIs, or a FinSpec file for FIX today (with support for other financial protocols like SBE on our roadmap). See FinSpec for how to create one.
Can I mix rendered schemas with hand-written prose on the same page? Yes — you can embed API definition fragments directly inside a regular Markdown page, which is useful when you want narrative context around a specific endpoint or field.