Real-world Patterns 4: Interactivity and Machine-readable documentation
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.
0 comments