Markdown support - why only in descriptions?

[Tadhg Pearson]

I've been starting to use the new Swagger 2.0 YML format, and I really appreciate the markdown support in the description field. It's an essential feature to keep the documentation readable but detailed that I can link out to external sites for more info, reference tables etc.

But what I don't understand is why this feature only applies to descriptions. There are many other elements that could benefit from markdown support. The "format" field would be one obvious example:

        - name: departure_date
          in: query
          description: The date on which you would like to depart.
          required: true
          type: string
          format: "[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date"
          default: "2015-10-14"

This would clarify for the user exactly how to format the date variable, what valid values may be allowed in this string field, and provide them with full reference information.
The API summary field would seem like another obvious candidate.

I don't really understand why the use of markdown is so limited. Is there a reason?

[Marsh Gardiner]

Hi Tadhg!

I agree that summary feels like a short description and should support markdown. I'm less convinced of the enumerated format attribute, which seems like something the tooling could deal with, similar to validating a string or an integer.

Personally, I find "summary" and "description" redundant. I'd prefer to have a human-friendly name (since "operationId" feels like more of a machine-name) than a "summary" field, though I guess there's nothing stopping me from using "summary" in that way.

Marsh

[Ron Ratovsky]

The decision around where to include GFM support was based on the current implementation of swagger-ui, or so I believe. 

Including it in the summary field would have introduced potential issues with the current display of the ui. While it may seem off imposing restrictions on the spec based the tools around it, one of the things that currently characterize Swagger is its ecosystem so we need to take it into account.

The format field is taken from JSON Schema, and while there are no restrictions about adding GFM to it, it breaks its intent. The format is intended to be machine readable and processed automatically by tools. Even customized strings, beyond the common formats, are valid as the tools normally allow extensions to provide validations based on those formats. If you need to provide further details on the format, I'd suggest using a different field for it.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

-----------------------------------------

http://swagger.io
https://twitter.com/SwaggerApi
-----------------------------------------

[Tadhg Pearson]

Thanks for the info.

As a new user, it wasn't obvious for me that format field supposed to be machine-readable, I didn't see it in either the json or text spec.

What are typically valid values for the format field? What field would you suggest for end-user documentation regarding the format of a request parameter?

Similarly, what is the effective usage of the summary field you're referring to. Editor.swagger.io displays it in a similar manner to a description. Is it supposed to be more like a title or tagline?

[Ron Ratovsky]

Regarding formats, have you seen - https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#data-types?

Regarding the summary, I'm not sure where it reflects in the editor, but in the ui it can be seen on the right side of each operation - http://petstore.swagger.io/#!/pet.

Additional information is probably better off in the description field.

[Tadhg Pearson]

Aha, thanks Ron.

So, are there plans to support more formats in future versions of swagger, maybe enumeration, currency, email-address, iata-location-code, or maybe even regular expression patterns? That could be kinda cool!

[Ron Ratovsky]

Technically, they are already supported (regex is supported via the 'pattern' property, regardless of the format, enumerations are supported via 'enum').

If you're asking about actual validation, we do try to add some additional common formats over time. The real goal is to allow validation point extensions so that users could customize those (eventually, we can't provide support for all, especially since it's a free-form field).