search

fleetdm / fleet

Open-source platform for IT, security, and infrastructure teams. (Linux, macOS, Chrome, Windows, cloud, data center)
https://fleetdm.com
Other
2.74k stars 393 forks source link

Create proof of concept of new interactive API documentation #8150

Open lukeheath opened 1 year ago

lukeheath commented 1 year ago

Goal

As an Engineer, I want API docs that allow me to interact with elements and objects on the page so that I can better understand nested objects and how they relate.

Notes

Two options have been selected for evaluation:

  1. https://stoplight.io/
  2. https://redocly.com/

Requirements

  1. Evaluate API documentation platforms above and choose a platform for the proof of concept.
  2. Create Fleet account and migrate a couple of our more significant API endpoints (like GET /hosts).
  3. Generate docs and make sure PoC provides a good overview of the available features.
  4. Share with the community and get feedback.

Key questions

  1. Can it be generated from OpenAPI specs?
  2. Is it easy to update?
  3. Is it easy to navigate?
  4. Can it be branded with Fleet styling?
lukeheath commented 1 year ago

Also evaluating Postman's new doc generator: https://blog.postman.com/open-api-3-0-documentation/