Define formal media type (MIME type) for Swagger Object

[philipashlock]

A media type of application/swagger+json has been suggested on the mailing list before. I would recommend formally declaring this as part of the spec.

RAML defines its media type as application/raml+yaml

API Blueprint defines its base media type as application/vnd.apiblueprint.ast plus similar ones for other serializations

[philipashlock]

For what it's worth, the White House open data policy is currently documenting application/swagger+json for metadata provided by federal agencies: https://project-open-data.cio.gov/v1.1/api/

If this should be changed, please flag it is an issue on https://github.com/project-open-data/project-open-data.github.io/issues

[webron]

👍

[olensmar]

I'm all for it and would like to go so far and suggest different mime-types for different encodings and Swagger versions

application/swagger-v20+json
application/swagger-v20+yaml
application/swagger-v12+json
application/swagger-v12+xml

(not really sure we need to add xml for 1.2 but it was in the spec as far as I can remember)

since Swagger 1.2 has separate files for resource listings and api declarations I suggest we make the api declaration implicit and have a separate mime-type for the resource listing

application/swagger-v12-resource-listing+json
application/swagger-v12-resource-listing+xml

or alternatively we make both the api declaration and resource listing explicit;

application/swagger-v12-resource-listing+json
application/swagger-v12-api-declaration+json
application/swagger-v12-resource-listing+xml
application/swagger-v12-api-declaration+xml

If we're aligned I can submit this to IANA... let me know your thoughts

/Ole

[dilipkrish]

@olensmar Not really sure we need to separate resource listing and api declaration. Its implicit by definition that if its application/swagger-v12+json we're going to get a document that conforms to the swagger12 spec. likewise for swagger2 also. Its no different that today where application/json covers both documents (files). In the case of swagger 1.2 the protocol to access the resource listing to get to the api declarations is a shared understanding described by the spec.

As an aside, related to swagger-api/swagger-ui#708 would you be able to assist/ hand-hold so I could also register

application/swagger-v20+hal+json

I'm starting to experiment with a few ideas with swagger and hypermedia support. The thinking is that if we could combine HAL with swagger it would give a rich interactive experience. An on-demand swagger-ui if you will, similar to hal browser. I have very rough ideas that I hope to formalize soon. Initially trying to prototype it in spring using springfox.

[olensmar]

@dilipkrish thanks! I'd love to talk about hypermedia support in swagger, it's getting asked for in every talk I've done on swagger over the last weeks. I personally think that using the extension mechanism is a good starting point; if we can agree on a set of extensions that add hypermedia-related constructs to a Swagger definition those can be used by related tools without having to change the spec itself - and if they gain a lot of traction we could discuss putting it in the next major revision of the spec.

Regarding the mime-type - I still think there are use-cases where it might be good to be able to differ between resource listings and api declarations - but those might be very application-specific so we can leave them out for now. In that case I suggest we just go with:

application/swagger-v20+json
application/swagger-v20+yaml
application/swagger-v12+json
application/swagger-v12+xml

what about also having

application/swagger+json
application/swagger+yaml

as aliases for the latest version of the spec? (2.0) Or is that some kind of anti-pattern that I'm not aware of?

/Ole

[lovelydinosaur]

Is there any formal progress on a "application/swagger+json" media type? I'm working on generic client tooling right now, and the lack of a media type for swagger is a minor point of awkwardness there (eg can interact with other schema and hypermedia types without having to explicitly specify what type of media they should be interpreted as, but not so with swagger)

[fehguy]

I think this is a very good idea to add in the next spec version

[cabbonizio]

+1

[jharmn]

+1