OpenAPI for Documentarians

A presentation at APItheDocs in June 2023 in Amsterdam, Netherlands by Lorna Jane Mitchell

Slide 1

Slide 1

for documentarians Lorna Mitchell, Redocly @redocly ~ @lornajane

Slide 2

Slide 2

Why OpenAPI? A standard way to define an HTTP API for use by others both humans and machines •Widely supported open standard •Actively developed in the open @redocly ~ @lornajane

Slide 3

Slide 3

API lifecycle @redocly ~ @lornajane

Slide 4

Slide 4

Get to know OpenAPI @redocly ~ @lornajane

Slide 5

Slide 5

OpenAPI structure @redocly ~ @lornajane

Slide 6

Slide 6

OpenAPI info Overview and metadata section @redocly ~ @lornajane

Slide 7

Slide 7

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

Slide 8

Slide 8

Markdown in OpenAPI OpenAPI description fields support CommonMark. In the description field, you may: •use Markdown •start with > to allow linebreaks that will not be rendered •start with | to preserve whitespace @redocly ~ @lornajane

Slide 9

Slide 9

OpenAPI paths @redocly ~ @lornajane

Slide 10

Slide 10

OpenAPI paths @redocly ~ @lornajane

Slide 11

Slide 11

OpenAPI schemas @redocly ~ @lornajane

Slide 12

Slide 12

Schema examples Give meaningful examples for every parameter/schema Message: type: string description: The message returned by the call example: You are great (Bonus points for making people smile!) @redocly ~ @lornajane

Slide 13

Slide 13

Response examples Responses allow multiple named examples examples: registration: description: “User registration” value: {“message”: “New user 22 registered”, “event_id”: 100007892345} login: description: “User login” value: {“message”: “User 17 logged in”, “event_id”: 100007892345} @redocly ~ @lornajane

Slide 14

Slide 14

OpenAPI schemas @redocly ~ @lornajane

Slide 15

Slide 15

OpenAPI references @redocly ~ @lornajane

Slide 16

Slide 16

OpenAPI components @redocly ~ @lornajane

Slide 17

Slide 17

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

Slide 18

Slide 18

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

Slide 19

Slide 19

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

Slide 20

Slide 20

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

Slide 21

Slide 21

API Documentarians @redocly ~ @lornajane

Slide 22

Slide 22

Postman State of the API report 55% of respondents cited “Lack of Documentation” as the biggest obstacle to consuming APIs https://www.postman.com/state-of-api/ @redocly ~ @lornajane

Slide 23

Slide 23

Resources •https://lornajane.net •https://redocly.com •https://openapi.tools •https://www.postman.com/state-of-api/ @redocly ~ @lornajane