A presentation at APIDays London in in London, UK by Lorna Jane Mitchell
API Description Pipelines Lorna Mitchell, Redocly @redocly ~ @lornajane ~ @lornajane@indieweb.social
Every API is different Standard processes never quite fit. @redocly ~ @lornajane ~ @lornajane@indieweb.social
Gather Inputs •Fetch/Generate OpenAPI descriptions •If differing standards apply, lint now @redocly ~ @lornajane ~ @lornajane@indieweb.social
Combine and Enrich •Combine API descriptions •Add summaries, descriptions, documentation •Add examples, really good ones @redocly ~ @lornajane ~ @lornajane@indieweb.social
•Overlays or Redocly Decorators for repeatable edits @redocly ~ @lornajane ~ @lornajane@indieweb.social
Run Checks •Check description meets expected standards •Run API tests against mock servers (Arazzo describes flows) @redocly ~ @lornajane ~ @lornajane@indieweb.social
… the tide turns … @redocly ~ @lornajane ~ @lornajane@indieweb.social
Plan Destinations •Docs: internal, external, partner •API gateways •SDK Generation •… other downstream tools @redocly ~ @lornajane ~ @lornajane@indieweb.social
Filter •Subset of API for one audience •Filter private endpoints out •Split up for easier publishing/sharing @redocly ~ @lornajane ~ @lornajane@indieweb.social
Enhance •Replace summary/descriptions for translated docs output •Hint to AI tools on costs •Add metadata for downstream tools to use @redocly ~ @lornajane ~ @lornajane@indieweb.social
Bundle Some tools require a single file as input @redocly ~ @lornajane ~ @lornajane@indieweb.social
Resources •https://lornajane.net •https://redocly.com •https://openapis.org @redocly ~ @lornajane ~ @lornajane@indieweb.social
API descriptions power every part of our API lifecycles, but they also go through evolutionary steps of their own. In this session, we’ll talk about the stages that make up an API description pipeline from gathering inputs to delivering output descriptions to each destination. We’ll discuss how to enrich API descriptions, ensure compliance with governance standards, and tailor APIs for multiple output platforms. You’ll learn about best practices and tools, and when and why you’d choose to add them to your own setups. This talk is ideal for developers and architects seeking to streamline API workflows and deliver robust, multipurpose, well-documented APIs.
