Real-world Patterns 4: Interactivity and Machine-readable documentation
Key points in this video
- 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.
- 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.