OpenAPI Upgrades The what, the why, and the how Lorna Mitchell API Architect, TM Forum

OpenAPI 3.0 was a long time ago lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social

Your API has new readers Why upgrade? lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social

Beyond the docs portal 2017 Today Developers Everything from 2017, plus Docs portals Governance and linting Code generators SDK and test pipelines AI agents lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social

3.1 • JSON Schema: works with every JSON Schema tool • Webhooks: the calls your API makes • $ref: fewer surprises • Flexible structure: paths are optional lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social

• • • • Tags: hierarchy for navigation Streaming: SSE, multipart $self: documents know their own URI HTTP methods: QUERY and any others 3.2 lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social

Your API description could be doing more for you. lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social

It’s a journey, not a task Upgrade strategy lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social

Map your landscape Where are you now? What should your new normal look like? lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social

Choose tools wisely Tool with no 3.1 support yet? Replace it. • • • • Design a new pipeline Upgrade or replace Tools for today’s needs openapi.tools lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social

Upgrade OpenAPI document lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social

Overlays: transforms for OpenAPI Edit once, re-apply on every update. • • • • • Improve the API description: IDs, descriptions, examples Add missing error responses Adjust server information for each environment Remove private or experimental endpoints Produce OpenAPI files for different purposes lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social

Upgrade strategy lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social

Your API description has been waiting for your attention. The standards were here all the time. What will you build? lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social

Thanks! learn.openapis.org lornajane.net openapi.tools tmforum.org Feedback, please! lornajane.net ~ tmforum.org ~ openapis.org ~ @lornajane.net (bsky) ~ @lornajane@indieweb.social