OpenAPI for Documentarians

for documentarians Lorna Mitchell, Redocly @redocly ~ @lornajane

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

API lifecycle @redocly ~ @lornajane

Get to know OpenAPI @redocly ~ @lornajane

OpenAPI structure @redocly ~ @lornajane

OpenAPI info Overview and metadata section @redocly ~ @lornajane

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

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

OpenAPI paths @redocly ~ @lornajane

OpenAPI paths @redocly ~ @lornajane

OpenAPI schemas @redocly ~ @lornajane

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

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

OpenAPI schemas @redocly ~ @lornajane

OpenAPI references @redocly ~ @lornajane

OpenAPI components @redocly ~ @lornajane

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

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

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

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

API Documentarians @redocly ~ @lornajane

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

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