Closed vlcinsky closed 10 years ago
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.
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
:+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.
It's done, and if you'd like a preview I would love feedback before we release it.
@fehguy - Sure, but I can't see a repo with an evocative name for the user "wordnik"... Where should we look at? :)
It is private now, but I've just added you to the repo. You should see it in your github dashboard now
@fehguy As author of this ticket I am also very interested. Would you give me a share?
@fehguy I'd love to check this out as well if possible.
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! :)
@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.
@quasipedia - I also wanted to thank you for the input! I hope the general Swagger population would enjoy it as well ;)
@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!
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.
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.
Great Jan! Please take a look and pass on any feedback on the docs.
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):
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
swagger-spec
But following rules shall be followed, to prevent confusion:
After this is written, existing documentation (mainly existing wiki) shall be reviewed and cleaned with respect to:
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.