A presentation at APItheDocs in in Amsterdam, Netherlands by Lorna Jane Mitchell
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
OpenAPI descriptions are an excellent way of having all information about an API in one place, and making that available to many different tools. As a standard, it can be difficult to get started with, and the resulting files are often large and unwieldy. In this session, you’ll get an overview of the structure of OpenAPI descriptions, details on taking advantage of OpenAPI features to create documentation, and some tips on working around common problems. We’ll look at some of the tools available to help you through various stages of the API lifecycle, and how these fit into your documentation workflow. This session is recommended for technical writers, engineers, technical leaders and anyone else wanting to make their APIs a better place for developers.
