API Description Pipelines

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