Swagger versioning and making Swagger looking like a real Standard

[vlcinsky]

Swagger tries to provide standardized method for documenting API, but current documentation fails in describing what is called Swagger Specification, namely there is really mess in explaining what versions of spec exist.

There is no page, which would list all currently existing versions of Swagger spec.

On page https://github.com/wordnik/swagger-core/wiki/1.2-transition there is in very beginning good advice "Not to be confused with the swagger framework versioning, the swagger specification itself is versioned for compatibility.", but on the same page I found headers, which confused me quite a lot:

Page has header: 1.2 transition

I assume, this is related to Swagger Specification (version 1.2) and how to update service specification from previous version s of Swagger Specification (which I believed was only version 1.1 so far)

The page has subheaders (all on the same level):

• 1.0 Resource Listing
• 2.0 API Declaration
• 2.1 API Declaration models
• 3.0 Credits

Hmm. Originally I assumed, current Swagger Specification is v1.2.

What is the 2.0 API Declaration? Where it comes from? The same for 2.1 API Declaration.

And what means 3.0 Credits? Is there any version 3.0? Version of what? Swagger Specification? Swagger-core? Or is there some other versioned concept named "API Declaration?"

Use (the boring) dedicated specification for describing Swagger Specification

Current documentation is mixing too many concepts, some specification of Swagger-spec, then set of related software components for different uses, and this all is somehow versioned all together.

I would propose to

• set up dedicated repository only for Swagger Specification. Call it swagger-spec
• use one branch per released specification version
• include JSON Schemas as "normative part".
• provide strictly descriptive (not narrative) description of artefacts and their structure there.
• provide references to other resources, if needed for information mentioned above
• provide part linking to older versions of such specification
• define terms and definitions. Namely distinguish between
  • "Swagger Specification Format" (SSF) - Format used for API specifiation
  • "API specified by SSF" - some API, defined by SSF
  • "Specification of Swagger Specification Format" (SoSSF) - proposed dedicated specification document itself
• agree on abbreviations SSF1.1, SSF1.2 etc. for referencing different versions of Swagger Specification Format.

But following rules shall be followed, to prevent confusion:

• no tutorial (it does not belong to specification)
• no source code, if not strictly part of specification (so allow JSON Schema, but do not include code for supporting tools)
• remove links to other external resources, which are not really necessary.

After this is written, existing documentation (mainly existing wiki) shall be reviewed and cleaned with respect to:

• correct use of agreed terms
• strictly distinguishing all different concepts
• in case, versions are referenced, strictly use agreed abbreviation SSF1.2, SSF1.1 etc. This shall minimize confusion with other versioned Swagger products.
• remove unnecessary stuff, which duplicates what is described in SoSSF and what is not needed for given purpose.

Simply stated: If you want Swagger becoming a standard - make Swagger looking like a standard first.

Currently this is not the case, but I wish it would become true. Swagger concept deserves it.

[eddieajau]

Completely agree. I'm still researching options but I like the theory behind Swagger and most of its structure, but the irony is the documentation for the API standard itself needs a lot of love (compare this repo with the RAML spec).

Moving the standard to its own repository is key, even if it's just one file. This also allows the community to issue pull requests to propose and make changes to the standard itself. That repo can then be dedicated to tutorials and examples for using the specification itself.

I'm happy to help have a go converting the current wiki pages into standard-ese if @wordnik would like.

[fehguy]

Hi folks, thank you for the feedback--as posted on our google group, we're currently redoing the documentation and encourage people to give feedback about it there:

https://groups.google.com/forum/#!topic/swagger-swaggersocket/NzYwaOMGoP0

[quasipedia]

:+1: from me. GitHub is our friend in this regards, as they recently introduced the rendered prose functionality, that would help a lot in keeping track of changes in the specification.

[fehguy]

It's done, and if you'd like a preview I would love feedback before we release it.

[quasipedia]

@fehguy - Sure, but I can't see a repo with an evocative name for the user "wordnik"... Where should we look at? :)

[fehguy]

It is private now, but I've just added you to the repo. You should see it in your github dashboard now

[vlcinsky]

@fehguy As author of this ticket I am also very interested. Would you give me a share?

[fehguy]

Yep, see here https://github.com/wordnik/swagger-docs/wiki/Swagger-RESTful-API-Documentation-Specification

[silas]

@fehguy I'd love to check this out as well if possible.

[quasipedia]

For those interested, I filed my feedback in form of issues in the repo of the specifications. Unluckily an issue is not the best form to express appreciation, so let me do that here instead: it looks like the upcoming specifications are a big, nice step forward compared with what is available right now!

Well done swagger team! :)

[fehguy]

@quasipedia thanks very much for the input! I hope to make the repo public this coming week after we do another rev of review.

Our goal is to get the current spec documented and clear, and guide the next version.

[webron]

@quasipedia - I also wanted to thank you for the input! I hope the general Swagger population would enjoy it as well ;)

[quasipedia]

@fehguy @webron - No problem! I'm a strong believer in free/open standards, so I'm only happy if I can share ideas (hopefully sometimes useful!) that will ultimately contribute to make swagger better → swagger more adopted → the API world more standardised → the world a better place! :)

Keep up the excellent job!

[fehguy]

Folks, i'm happy to announce that we have a rewrite of the swagger-spec documented here:

https://github.com/wordnik/swagger-spec

Many thanks to @webron in getting this together--we'll be ripping stuff out of the current site as well.

[vlcinsky]

Excellent work!!! I am now going to write this great news to my colleagues at SUPERHUB project, where we are trying to use it for our specifications.

[fehguy]

Great Jan! Please take a look and pass on any feedback on the docs.