Inlined API & Schema References

One of the most distinctive features of the FixSpec portal is its ability to inline-render interactive API endpoints and JSON schema fragments within descriptive text (as well as on a dedicated page). This lets developers view detailed technical information right inside the context they’re reading, without forcing them to navigate away and back.

Duplicating this technical information into your prose would be inefficient and error-prone — the endpoint definition and your description would inevitably drift apart. Instead, a custom container simply points to the external specification, and the portal renders it live.

💡 The 80-20 Rule

We recommend spending 80% of your time obsessing over your machine-readable schemas (OpenAPI, FinSpec etc) to make them as perfect, complete and accurate as you can get them. With these as a solid foundation, the amount of surrounding text you need to maintain drops significantly.

API References

The syntax to use this is:

markdown
:::endpoint
protocol=openapi
spec=fixspec
version=v5
id=api.v5.firms
:::

Where the following attributes are available:

Attribute Required Description
protocol Y "openapi" or "finspec"
spec Y The subfolder name within /apis
version Y The version of the machine-readable specification
id Y The fragment to display. For OpenAPI, this is the operationId. For FinSpec, it is {map}.{key}
expandable N Whether the fragment should be initially rendered in a collapsed form (expandable=true). The default is expandable=false, where the endpoint renders fully.

OpenAPI Example

markdown
:::endpoint
protocol=openapi
spec=fixspec
version=v5
id=api.v5.firms
:::

Collapsed FinSpec (FIX) Example

markdown
:::endpoint
protocol=finspec
spec=trading-fix-specification
version=2-2
id=messages.K6fZXnKK
expandable=true
:::

(JSON) Schema Reference

A schema is subtly different to a machine-readable API document, because it defines the format of the document itself. For example, a FinSpec document is a JSON file which must — itself — comply with a schema that defines it. A closer analogy might be an XSD document, which defines how an XML file should be structured.

The syntax to use this is:

markdown
:::schema
protocol=finspec
version=5.2
def=metadata
:::

Where the following attributes are available:

Attribute Required Description
protocol Y "openapi" or "finspec"
version Y The version of the machine-readable schema (omit the .json part)
def Y The fragment definition ($def) to display.

ℹ️ `$defs` Only

This fence is designed to render $defs fragments as opposed to inlined properties. This may require a small adjustment to your JSON schema.

Frequently Asked Questions

Can I show the same endpoint in more than one place?

Yes — the :::endpoint fence just points at the underlying spec, so you can reference the same id from as many pages as makes sense. There’s only one source of truth, so the rendered content stays in sync everywhere it’s used.

What happens if the spec changes after I've referenced it?

The page picks up the change automatically the next time it renders, since the fence always pulls live from the spec rather than a snapshot. There’s nothing to re-copy or keep in sync manually.

Which protocols are supported?

openapi and finspec today, for both endpoints and schemas. If you need another description language supported, drop us a line.