Create OpenAPI spec for Fleet API

[lukeheath]

Problem

The current markdown-based REST API docs do not provide an open, standard specification of our API.

Potential solutions

[mostlikelee]

I'd argue the request here isn't necessarily to replace our existing docs, but to build out an OpenAPI spec so we gain the ability to dynamically generate tests, postman collections, and if we so chose swagger docs.

[lukeheath]

@mostlikelee Good point. I updated the title to "Use OpenAPI specs to generate REST API docs" is that more accurate?

If we created a process whereby OpenAPI specs could be generated into our current Markdown doc format, it would be easier to adopt since it wouldn't require adopting a new API doc structure.

[lukeheath]

So then the question becomes, is having an OpenAPI spec valuable enough that it's worth:

1. Writing the spec from scratch.
2. Writing something to translate that into our Markdown format.

That would be a good amount of work (one engineer, one sprint, I'm guessing?), there would need to be solid and clear examples of the benefits to Fleet and Fleet's community.

[georgekarrv]

Also allows us to easily generate SDKS for other languages to use our API like Python / Rust / etc

[Jiyda]

Hi All! I was poking around the Fleet repo just to get a feel for what it can do. While I was digging into the API docs, I spotted this open issue about switching to OpenAPI specs. I've created quickly a script that transforms the current Markdown API docs into OpenAPI specs. Some endpoints were omitted due to invalid JSON, and there may be other discrepancies since I didn't manually compare it against the markdown file. However, this should serve as a good starting point.

Below is the OpenAPI JSON format output: open_api_specs.json

Screenshot from Swagger-ui

Let me know if this is what you're looking for, and I’d be more than happy to create a PR and include the script as well.

[lukeheath]

@Jiyda Wow, this is cool! Thank you for doing that. We'd love for you to put in a PR with the script. We could tie it into our CI/CD so that whenever the markdown file is updated, it regenerates an OpenAPI spec. How about in a new directory at /tools/openapi?

cc @georgekarrv @nonpunctual

[nonpunctual]

@georgekarrv @lukeheath this is great! How do we manage the API endpoints that currently don't conform?

[lukeheath]

@nonpunctual We'd likely iterate on the script to resolve the edge cases.

[lukeheath]

I'm closing this for now, but is still an option if we implement OpenAPI but still really want markdown docs.

[fleet-release]

OpenAPI weaves, like a spider's web, a path. Clear, standard, shared map.

[lukeheath]

On second thought, I'm just going to re-spec this as creating a new OpenAPI spec for the Fleet API.

[dherder]

adding the terraform provider based on the OpenAPI spec would be desirable. https://developer.hashicorp.com/terraform/plugin/code-generation/openapi-generator

[nonpunctual]

Really great article on creating API specs: https://johnholdun.com/apis/full/

[JoStableford]

Related to a Slack conversation