Wiki missing an example of Kind: Spec

[stokedout]

Hey, regarding specs, it says that specs shouldn't be inlined but there's no reference example of how a Spec should be formatted. it would be good to have a copy-paste example of the Spec kind just like the others on this wiki page as a reference. Would it be possible to get one?

To import them with Registry YAML, registry apply uses the filename field of specs to identify the files to upload and it looks for these files in the same directory where the referring YAML file is found.

File or files? Would you be able to provide an exhaustive list of inputs for filename?

mimeType on Spec seems optional, what is it needed for?

[timburks]

Hi, yes, we can add an example spec. The registry is format-agnostic, so specs could be any version of OpenAPI or any other single-file format and we have been uploading multifile specs (such as collections of .proto) files as zip archives.

I'll also try to clarify that language -- we're assuming that even multifile specs like protos get put into an archive, and there the filename would be the filename of the archive. If the archive doesn't exist, registry apply creates it by zipping up everything in the same directory as the info.yaml file that describes the spec.

mimeType is optional but strongly needed by downstream tools (linters, code generators, etc). We're currently uploading API specs as blobs and not trying to internally identify their types (possibly a project for the future).

[timburks]

Here is an example of a proto-style API description (in info.yaml) and a corresponding set of protos that get zipped up and uploaded by registry apply. If you clone this repo, you can just run registry apply -f apis -R at the root of the repo to try this yourself.

Here is an example of an API with two OpenAPI descriptions (one in the older Swagger/OpenAPI 2.0 format and one in OpenAPI 3.0). Both specs are uploaded when you run registry apply -f apis -R at the root of this repo (note that it's different from the one above).

[timburks]

(keeping this open until the wiki is updated)