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, and 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, generating interactive docs, documentation testing and automated API workflows.