A presentation at FOSDEM 2024 in in Brussels, Belgium by Lorna Jane Mitchell
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
OpenAPI Specification is a machine and human readable way to describe APIs, from endpoints to examples. From these descriptions we can generate documentation, create libraries, and ensure that our users know exactly what to expect from our APIs. This talk introduces you to the OpenAPI standard, showing how to describe APIs and looking at some popular API examples. Good tools are essential so we’ll look at some of the open source tools available to working with OpenAPI easier. We’ll cover the benefits of using an open standard to describe your APIs and discuss what you can do next, like publishing documentation, generating code, and teaching LLMs new tricks. Learn about what’s coming up in the world of OpenAPI, and how to get involved with this open standard and its community.
