Key points in this video

Interactive documentation

• Users can call an endpoint right from their browser
• Useful for APIs that can be tested standalone.
• Can be embedded in reference docs or exist separately
• Can be combined with code examples
• Platforms like Swagger, apiary.io and ReadMe.com provide this functionality, but you can also write yours
• Tip: Interactive or not, don’t neglect the actual documentation content.

Machine-readable documentation

• Written in a structured format, which can be parsed by code (“machine-readable”)
• Examples: OpenAPI specification, Postman collection, API Blueprint specification
• Can also be generated by code
• Structured nature leads to several possibilities, such as generating reference docs, generating libraries (see https://openapi-generator.tech), generating interactive docs, documentation testing and automated API workflows.