search

RepreZen / Semoasa

Specification Extension Metadata for OAS Annotations (Semoasa) is a machine-readable format for extensions to Swagger/OpenAPI 2.0 and 3.0 specifications.
29 stars 1 forks source link

Suggest adding a (cut-down) info object at the root #12

Open MikeRalphson opened 7 years ago

MikeRalphson commented 7 years ago

Which might look something like:

Fixed Fields
Field Name Type Description
title string REQUIRED. The title of the SEMOASA documentation.
description string A short introduction to the documentation. CommonMark syntax MAY be used for rich text representation.
contact Contact Object The contact information for the documented extensions.
version string REQUIRED. The version (or date in ISO-8601 format) of the SEMOASA document (which is distinct from the openapiExtensionFormat property.
tedepstein commented 7 years ago

Nice idea, especially because this allows self-identification of the publisher, who may or may not be the same party as the provider. I'm thinking that we should make that intention clear in the Description column, also allow a similar contact property in the Provider Object, and add a contacts catalog under components to keep it DRY.

Also, consistent with OAS3, our spec uses the term "document" to refer to the physical file containing a SEMOASA Extensions Object.

Field Name Type Description
title string REQUIRED. The title of the SEMOASA document.
description string A short introduction to the document. CommonMark syntax MAY be used for rich text representation.
contact Contact Object | Reference Object The contact information for the publisher of the SEMOASA document.
version string REQUIRED. The version (or date in ISO-8601 format) of the SEMOASA document (which is distinct from the openapiExtensionFormat property.

I'm on the fence as to whether title should be required. Is this so we can present the source document in a UI, or in generated human-readable documentation? Or is it for some other purpose?

MikeRalphson commented 7 years ago

Yes, I was mainly thinking of generated human-readable documentation. :smile:

I don't think title need be required.

tedepstein commented 7 years ago

Wow!!! :-)

tedepstein commented 7 years ago

Very cool to see this, @MikeRalphson . Did you write a generator to do this, or did Shins auto-magically adapt to this new format? Either way, pretty impressive.

If there's something here that people can use today, to generate similar extension docs from a SEMOASA spec, I'd like to add it to Implementations in the Readme.

MikeRalphson commented 7 years ago

I'd love to say shins could automagically derive such documentation from an arbitrary yaml file, but no, it's just a port of slate to node.js - the 'clever' bit is done by three small templates added to widdershins.

Will PR to the Readme.