Introduction to OpenAPI

Introduction to OpenAPI Lorna Mitchell, Redocly @redocly ~ @lornajane ~ @lornajane@indieweb.social

OpenAPI https://openapis.org Open standard for describing HTTP APIs. •machine- and human-readable •JSON or YAML @redocly ~ @lornajane ~ @lornajane@indieweb.social

OpenAPI structure @redocly ~ @lornajane ~ @lornajane@indieweb.social

OpenAPI info Overview and metadata section @redocly ~ @lornajane ~ @lornajane@indieweb.social

OpenAPI YAML openapi: 3.1.0 info: title: Excellent API summary: An API for Excellence description: > This API is modern, and will make your applications 67% more excellent. Write as many words as you like here, markup is also supported. version: 1.0.0 license: name: Apache 2 identifier: Apache-2.0 externalDocs: url: https://example.com/docs description: Read more about this API, tutorials, and libraries @redocly ~ @lornajane ~ @lornajane@indieweb.social

OpenAPI paths @redocly ~ @lornajane ~ @lornajane@indieweb.social

OpenAPI paths @redocly ~ @lornajane ~ @lornajane@indieweb.social

OpenAPI schemas @redocly ~ @lornajane ~ @lornajane@indieweb.social

OpenAPI references @redocly ~ @lornajane ~ @lornajane@indieweb.social

OpenAPI components @redocly ~ @lornajane ~ @lornajane@indieweb.social

Power of OpenAPI @redocly ~ @lornajane ~ @lornajane@indieweb.social

@redocly ~ @lornajane ~ @lornajane@indieweb.social

@redocly ~ @lornajane ~ @lornajane@indieweb.social

@redocly ~ @lornajane ~ @lornajane@indieweb.social

@redocly ~ @lornajane ~ @lornajane@indieweb.social

@redocly ~ @lornajane ~ @lornajane@indieweb.social

Tools for OpenAPI https://openapi.tools/ @redocly ~ @lornajane ~ @lornajane@indieweb.social

OpenAPI editors The best editor is the one you know •Programmers’ editor, with plugins •Graphical editors @redocly ~ @lornajane ~ @lornajane@indieweb.social

OpenAPI governance Quality standards, consistently enforced •Agree written standards •Humans to check changes •CI (continuous integration) for all changes •Start small @redocly ~ @lornajane ~ @lornajane@indieweb.social

OpenAPI linting Let the machines do the work (within their skillset) •Validate OpenAPI •Enforce descriptions, examples •Follow naming conventions •Configure the rulesets for your needs @redocly ~ @lornajane ~ @lornajane@indieweb.social

OpenAPI documentation Read the docs for your docs! •Pull request previews help early feedback •Build/deploy should be fast and often •Track your key metrics (e.g. views) @redocly ~ @lornajane ~ @lornajane@indieweb.social

OpenAPI Community @redocly ~ @lornajane ~ @lornajane@indieweb.social

OpenAPI Community •Part of the Linux Foundation •Standard is developed in the open •https://openapis.org •Public GitHub repository •Active Slack groups •Weekly technical meeting @redocly ~ @lornajane ~ @lornajane@indieweb.social

OpenAPI SIGs Special Interest Groups (SIGs) focus on adjacent/upcoming standards •Workflows describe a sequence of API calls •Overlays map repeatable amendments to an OpenAPI file •OpenAPI 4.0 is under development (release due late 2024) @redocly ~ @lornajane ~ @lornajane@indieweb.social

OpenAPI Open standard for API descriptions @redocly ~ @lornajane ~ @lornajane@indieweb.social

Resources •https://openapis.org •https://lornajane.net •https://redocly.com •https://openapi.tools @redocly ~ @lornajane ~ @lornajane@indieweb.social