[Announcement] Call for proposals - Swagger Documentation

[Ron R]

As a step to improve Swagger, we're looking to improve its documentation.
Right now we have a set of wiki pages which are not optimally organized.
This refers to the spec, swagger-core and any other swagger projects developed by Reverb/Wordnik.

Based on your experience with Swagger's documentation so far, we would like your opinion about the following:

1. What else would you like to see inside the documentation (missed topics, explanations...)?
2. How would you like to see the documentation organized?
3. Would you prefer the documentation to be in github's wiki or in some external dedicated website?
4. If an external website, are there any tools you'd like to see used or can recommend to be used for the documentation (such as Sphinx)?

Obviously, we have a few ideas of our own, but we'd love to hear the opinion of the community and deliver a product that better suits everyone.

Of course, if you have any other suggestions, feel free to write them here as well.

[tony tam]

Some of the requests I've seen:

* Move the spec to a separate repo (https://github.com/wordnik/swagger-core/issues/382)

* Do a better job explaining fixes in minor releases (https://github.com/wordnik/swagger-ui/issues/363)

* More samples, and better explanations of them

* The model introspection needs better documentation, and how you override it

* How the various pieces fit together: swagger-core, swagger-ui, swagger-codegen are not clear to everybody

* There are a bunch of very mature implementations in different languages, such as in .net and php.  Maybe some samples from those languages in the docs?

There are a zillion different ways to configure swagger with Java.  I know it's hard to do all of them, but there must be a better way than one-off samples.

[tony tam]

Another piece of feedback, mostly for swagger-ui:

* List the supported browsers

* Included detailed licensing info on each project

[Aaron Conran]

One thing that I'd like to see is Swagger able to associate a set of CRUD methods with a particular model.

I'd like to be able to introspect the api endpoint and determine the create, read, update and delete methods for say the "pet" model. Of course we can make some assumptions based off of standard REST principles but Swagger does not dictate that these be followed. What do you think of this idea?

[Andrew Eddie]

On Thursday, 16 January 2014 07:36:56 UTC+10, Ron R wrote:

As a step to improve Swagger, we're looking to improve its documentation.
Right now we have a set of wiki pages which are not optimally organized.
This refers to the spec, swagger-core and any other swagger projects developed by Reverb/Wordnik.

Based on your experience with Swagger's documentation so far, we would like your opinion about the following:

1. What else would you like to see inside the documentation (missed topics, explanations...)?

I think the priority needs to be organising the spec' better so we can actually see what else is potentially missing.

1. How would you like to see the documentation organized?

The specification itself needs to be in a single, specification-ese (numbered sections, version controlled, RFC 2119, etc) document where the schema is clearly laid out. I also, initially, had trouble joining the dots between what the resource listing is and how that moves onto the API declaration. A simple diagram showing the hierarchy would be great.

Tutorials and references need to be clearly separate from the main specification. The spec' should be clearly versioned and I'd recommend adopting Semver so that it's clear when there are backward compatibility problems in the specification. In that respect when you make a breaking change (requiring a migration of files, for example, you'd jump from version 1.x to 2.0.0).

1. Would you prefer the documentation to be in github's wiki or in some external dedicated website?

I think the specification should be a single file in it's own repository. This allows you to tag the version of the document but also allows the community to make pull requests for future changes. Tutorials could either be wiki items or markdown files in a `/docs/` folder (potentially allowing you to publish the whole shebang with Github pages).

1. If an external website, are there any tools you'd like to see used or can recommend to be used for the documentation (such as Sphinx)?

Whatever works for you guys, but the important thing is to have the raw documents on Github.

 

Obviously, we have a few ideas of our own, but we'd love to hear the opinion of the community and deliver a product that better suits everyone.

Of course, if you have any other suggestions, feel free to write them here as well.

I'm happy to help review or refactor the existing docs if you'd like.  I'm sure more things will come up as I dig into using the spec' more myself.

Regards,

Andrew Eddie

[Ron R]

Aaron,

This is a suggestion you may want to raise regarding the future Swagger Spec, but I don't think it relates to the current documentation revamp.
If I'm mistaken, feel free to explain further.

[Ron R]

Andrew,

Thanks for the comments.
I'm actually concentrating on the rewrite of the Swagger Spec in a more formal language, just as you suggested.
I'm still trying to decide whether to have one long page with all the spec or split it into several pages as it getting annoyingly long.
I can understand the reasoning of versioning for a single page, but I believe we can also control the versioning on several pages.

[Andy Chillrud]

As a new user of Swagger, one thing that I would find useful is a document listing all the Swagger annotations, with a complete listing of all the attributes of each annotation, and an explanation of the function of each attribute.

Also a list of the non-Swagger annotations (JAXB, Jackson, etc.) that impact Swagger, and a description of how these affect Swagger.

Much of this is available in the existing documentation, but is incomplete, and is scattered.

Thanks,

Andy

[Ron]

Andy,

Not saying this is the solution, but out of curiosity, would a java-doc of the interfaces be enough to describe them or do you expect additional documentation?

This is unrelated to the effects of non-Swagger annotations which need to be documented separately.

--
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/groups/opt_out.

[Andy Chillrud]

Java-docs would be fine.

[Rion Dooley]

• +1 for clearly explaining how all the pieces fit together.
  
• The projects tend to stay pretty closely integrated, but they do get out of sync. This needs to be said right up front and noted in each project where inconsistencies occur.
• Polymorphism and how it is implemented in a model is not explained well in the documentation. It also does not seem to be supported in the current swagger-codegen, which relates to the previous point.
• The spec itself should be in its own project with documentation and examples just on authoring swagger docs.
• Core, ui, and codegen should reference examples and documentation from the separate spec project
• Github is a sufficient place for the docs IMHO. I find it helpful to be able to check them out and view locally...especially when I'm offline.
• I liked how you handled the 1.1 - 1.2 transition. 
• The material on specifying auth and how that impacts the behavior and assumptions of UI, core, and codegen was not clear. We never were able to get a basic OAuth 2 setup it working with any of the tooling, so we wound up hacking in a solution.
• It is not clear how to handle multiple content types either in the spec or the related projects. Do we replicates the parameters array for each content type? Is there a discriminator field for parameters based on content type? Do we replicate the method? We never understood this feature, so we never took advantage of it which is unfortunate since our API supports content negotiation.

Rion

[Ron]

Thanks for all the comments.

Rion - regarding the multiple content types support - you can simply set it for the whole resource in the API Listing or per Operation (which will override the definition of the API Listing). This is a list of content types, so no need to duplicate anything.

However, if you have further questions regarding this point, please open a new thread here and we'll do our best to assist. I've already clarified this in the upcoming rewrite of the spec.

--

[Mukesh Jha]

Please explain step by step how to use/setup Swagger with and without server integration in JAVA.

Thanks

[Marten Feldtmann]

I implemented the swagger specification for a Smalltalk based environment, but I have to admit: I spend so much time to reread the documentation over and over again just to find out what is allowed, supported or possible. And even now there are more questions opened how much of the JSON schema is possible to use or allowed in various places of the swagger specs.

I downloaded swaggerui from github, installed it at my development site and viewed the standard projects and got messages from my browser, that some depreciated methods are still used (but overall it worked)  - then I looked at the official site - there my browser did not print any console messages.

[Ron]

Marten,

The revised spec is pretty much done and going to be released to the public soon. I hope you'll find it easier to follow and more accurate to read.
Are you going to release the Smalltalk library as an open source?

On Tue, Mar 4, 2014 at 8:20 AM, Marten Feldtmann <marten.f...@googlemail.com> wrote:

I implemented the swagger specification for a Smalltalk based environment, but I have to admit: I spend so much time to reread the documentation over and over again just to find out what is allowed, supported or possible. And even now there are more questions opened how much of the JSON schema is possible to use or allowed in various places of the swagger specs.

I downloaded swaggerui from github, installed it at my development site and viewed the standard projects and got messages from my browser, that some depreciated methods are still used (but overall it worked)  - then I looked at the official site - there my browser did not print any console messages.

[John O'Conner]

I'm new as well, and my first thought while taking my first steps was this:

Where's the documentation for each annotation and its parameters? I want to know what the annotation does and what it produces.

[Ron R]

To anyone who follows this thread - the rewrite of the spec has been released and can be found here - https://github.com/wordnik/swagger-spec/
Keep in mind, this is not a new version of the spec but rather a formalization of it.

[Jo Rabin]

Excellent to hear - I have been looking at swagger for a few weeks now and this didn't show up on the radar.

One thing that might help is that the link on the petstore demo points you to swagger.wordnik.com for more information, but that leads back to the petstore demo not to further info about Swagger. 

Once you know that what you are looking for the petstore demo is an excellent resource but I must admit I've found it to fade in and out of working well, I posted just now that it seems to have stopped working again.

I think a full schema would be really useful if not an essential missing piece. After Googling around quite a bit last thing I saw on this was a note from last September which points to an incomplete copy. Same, I think, as the one in the swagger-core repo.

I don't know if this is helpful but I can generate an annotated schema from my implementation (Java) which has a few questions in it and undoubtedly lots of errors - but it is more complete than the latest one I have seen, and contains information about the purpose of fields, not just what they are, and might act as a useful starting point for a more complete and exact definition of 1.2.

I'm more than happy to make it available, I'd benefit hugely from correction of my misunderstandings - should I post it on this list?

Thanks for making Swagger - as I mentioned in another post, I've found it inspirational. 

Jo

[tony tam]

Thanks Jo, we are working on a proper schema for the spec right now

[John Dunlap]

Just a thought: I don't know if this makes sense for your use case but I'm pretty sure you could get an instance of Atlassian Confluence for free because you are open source project. In my opinion, it's the best wiki out there.

On Wednesday, January 15, 2014 4:36:56 PM UTC-5, Ron R wrote:

[Ron]

You're right, they do offer a free license, but for now we're trying to concentrate everything in Github.
It's definitely a good idea should we decide to pull out of it though.

--

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.

[gagandeep sharma]

As a new user of Swagger, I was struggling to find the json nodes for different feature like accept request type etc. I think that all should be documented in the spec it self. 

[Ron]

Thank you for the input, but is it not clear from the current spec documentation - https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md ?

--

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.

[Lloyd]

I'm new in web-development, it would be nice to have more detail in documentation, Like a step by step instruction, the commands used, the location of file for setup/configuration and what to add/edit, a working sample on how to use swagger and how to test it, screenshots perhaps and so on.

I'm currently using swagger-php and followed this instruction http://zircote.com/swagger-php/. But I'm still stuck in "using swagger-php" page, I cant get it working. :(

Also, I would like to implement swagger in codeigniter. Is it possible? I cant find any sources using swagger in codeigniter.

I appreciate your effort and very thankful for that. God Bless!

best regards, 

Lloyd

[sai...@gmail.com]

I am a developer and am evaluating options for REST API documentation for my upcoming project. I was very excited to find Swagger but ultimately disappointed due to a lack of proper step by step start here type of guide. After a few weeks I am still struggling to get a head start with this.

[Rion Dooley]

I agree that the examples could be improved. The pet store api isn’t remotely close to the level of complexity that the target audience seems to be interested in, but the spec does give you a lot of flexibility to describe most of thing things you would need to do with a rest API. Additionally, the tooling they’ve built up around it is outstanding. I would suggest 3 things when you’re learning Swagger.

1. If you’re trying to define existing APIs, use the editor to help you author the JSON. There are some things in the spec that really aren’t clear and the highlighting and validation in the editor helps you catch these very quickly. http://editor.swagger.wordnik.com/#/
2. Check out existing APIs using swagger for examples of how to define different things. Here is an example from our Agave API (http://agaveapi.co/live-docs)
3. Ask lots of questions. I’ve found the list to be rather responsive, so leverage the help while you have it. Every question you ask is a question someone else doesn’t have to. 

--
Rion

On Jul 5, 2014, at 3:13 AM, <sai...@gmail.com> <sai...@gmail.com> wrote:

I am a developer and am evaluating options for REST API documentation for my upcoming project. I was very excited to find Swagger but ultimately disappointed due to a lack of proper step by step start here type of guide. After a few weeks I am still struggling to get a head start with this.

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/NzYwaOMGoP0/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

[Ron R]

Lloyd,

swagger-php is a third-party library in the Swagger ecosystem.
Unfortunately, I can't comment regarding its documentation or the integration with codeigniter. However, feel free to contact its author with questions about it.

You may also want to look at the other PHP integrations available (https://github.com/wordnik/swagger-spec/#php) as one may suit your needs better.

[Ron R]

Can you give me some more info about your environment and what documentation (if any) you've used so far?

[Ron R]

Just to clarify - at the moment the editor is still a work in progress and may not produce 100% valid output (though we're really excited about it).

I think it would be impossible to write a sample that would capture every single aspect of Swagger in it, especially since we need to support different languages and different deployment environments (each having its own quirks).
However, we're working on rewriting the samples (no ETA yet) and adding a more elaborate guide to help touch the various aspects of documentation. This is currently relevant to swagger-core.

To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[Rion Dooley]

I cannot speak for the community, but in our case, the samples of value to us are example swagger docs for different api behavior. Custom auth, file upload and download, multiple content types and payloads per method, polymorphism, default values, floating point vs integer values, partial updates, pagination, common url query params across all collections, etc. I'm sure there are examples of these if I dig through the mailing list, but that is the point. It took us spending time on and off for weeks to figure this stuff out and then figure out what was and was not supported in the different versions of the swagger-* projects. We were willing to do that because there was value in fixing broken pieces and building up expertise in house, but for others, I can see how api blueprint can be an attractive alternative purely to document apis. A repo of examples could fix quite a bit of this, though. Feel free to take our docs to harvest examples of it helps.

-
Rion

To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

[Ron]

I agree that a large set of samples would be good, but it's also a nightmare to maintain.

I'd be very happy to get a list of things you were looking for in order to see how we can document them better (be it with samples or wiki pages).

--

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.

[Lloyd]

Thank you Ron!

Currently, I'm trying to test the swagger-php(no codeigniter for now). When cloning the git(for swagger-php), I can see there is an example folder, but I have no idea how to test it. I'm stuck in this page http://zircote.com/swagger-php/using_swagger.html, when I try this,

php swagger.phar /project/root/top_level -o /var/html/swagger-docs

I get this error,

Swagger-PHP 0.9.4

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

[ERROR] no valid resources found

Can't find more info about that. Hope you can direct me what to do. Also, if I can't get swagger-php working, I will try restler and swagger-asset. But if I can get it working, I will try implementing swagger-php in codeigniter.

best regards, 

Lloyd

[Ron]

Lloyd,

I would suggest opening an issue here - https://github.com/zircote/swagger-php and wait for zircote to respond.

[Rion Dooley]

+1 That is definitely a question for the zircote devs. You might also consider looking at Zen. They have good swagger support.

-
Rion

-----Original Message-----
From: Ron <web...@gmail.com>
To: "swagger-sw...@googlegroups.com" <swagger-sw...@googlegroups.com>
Sent: Mon, 07 Jul 2014 3:02 AM
Subject: Re: [Announcement] Call for proposals - Swagger Documentation

You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/NzYwaOMGoP0/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

[sai...@gmail.com]

Ron I have used the links on github wiki and gone through this forum where I stumbled upon this thread.

I understand the components in isolation, what I couldn't find was a guide that would help me setup swagger implementation (client and server) for my project.

For my project I want to use a mixed mode i.e. define some API's by hand to start with and as I move in to new stories, enhance existing APi's and dynamically generate the API documentation.

And along with it also be bale to setup my test data for the API.

Key question that I need answered are

1. How and what type of client can I setup that will allow me define some API's by hand

2. For a spring mvc project what annotations and structure I can follow to generate and publish API documentation along with my hand crafted swagger API documentation

3. How do I setup my test data and secure it to allow secured access for my clients

For my startup I want to setup an eco system for API definition, discovery and testing from scratch.

Arun

[Ron]

Arun,

I understand what you're struggling with, and I appreciate the input. It would definitely help us build a better documentation for Swagger.

Specifically for your case, would you mind opening a new thread with what you asked (you can simply copy/paste)?

I would love to try and walk you through it (even though some things may be out of scope) but that is not necessarily related to the original topic of the thread.

--

[Soonmok Kwon]

IMHO, decoupling JSON schema from swagger-spec is primary job to do. The reason is as follows:

The swagger-spec says the coupling between JSON schema and swagger-spec is: "Models Object ... follows a subset of the JSON-Schema specification. (Section 5.2.6)". But keywords in JSON schema definition are used in the objects other than the Models objects and they bring confusion. For example, "type", "format", "array", "items", "required" keywords are used in Parameters objects. So, there's multiple ways of defining JSON arrays. You can either model only the object for single entry in Models object and define array in Parameters object, or model both the single-object and array in Models object. IMHO, former method is side effect of JSON-swagger coupling and can cause unnecessary confusions to developers who deal with multiple body formats such as JSON, XML, or EXI. (Furthermore, the spec seems to consider only JSON as HTTP body. For example, there's no specification on how to specify or link XML body schema.)

The coupling between JSON-schema and swagger-spec seems to make it harder for swagger to support full-spec of JSON schema draft 4.

My proposals for those problems are as follows: 

1) Remove or rename all features that are from JSON schema (i.e. Models objects and others). 

2) Instead of re-defining JSON schema in Models object, just specify which features of JSON schema draft-4 is NOT supported by swagger TOOLS such as 'swagger-ui'.

3) Specify how to source external schema definition via URI, whether it is JSON schema or XSD.

Thank you for reading,

Soonmok Kwon

[Ron]

This is actually unrelated with the current documentation as what you're suggesting is a change in the spec.
We're currently working on the next version of the spec (to which you are welcome to join - (http://swagger.wordnik.com/). Additional voices are welcome.
As it seems the next version of the spec is going to adhere much closer to the json-schema with explicit restriction as to what is supported.

As for XML, technically, the model description can be reflected in an XML format.
However, we've gone the extra length to add some variance to the XML extensions. Mind you, this does not mean XSD support.

[Soonmok Kwon]

OK. 

I'm moving to that work group. Thank you.

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/NzYwaOMGoP0/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

[Ron]

Thank you! This kind of input is very important.

[David Wood]

Javadoc is a stop-gap measure IMHO.  As a very new user, I think you really need documentation on the annotations.  That's where the rubber meets the road - its the interface to the technology that many developers will initially be using.  Without it, we only have sketchy examples that don't cover all the possible usage and, I'm sure, power of swagger.  I'm looking forward to becoming a big user.  Thanks.

On Thursday, February 6, 2014 8:48:36 AM UTC-5, Ron R wrote:

Andy,

Not saying this is the solution, but out of curiosity, would a java-doc of the interfaces be enough to describe them or do you expect additional documentation?

This is unrelated to the effects of non-Swagger annotations which need to be documented separately.

On Thu, Feb 6, 2014 at 3:44 PM, Andy Chillrud <andy.c...@gmail.com> wrote:

As a new user of Swagger, one thing that I would find useful is a document listing all the Swagger annotations, with a complete listing of all the attributes of each annotation, and an explanation of the function of each attribute.

Also a list of the non-Swagger annotations (JAXB, Jackson, etc.) that impact Swagger, and a description of how these affect Swagger.

Much of this is available in the existing documentation, but is incomplete, and is scattered.

Thanks,

Andy

--

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-swaggersocket+unsub...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[Ron]

Hi David,

Thank you for the input. We have work in progress on the annotations documentation (javadocs + external doc) which is currently undergoing a review.
I suspect it would be available in the upcoming weeks.

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.

[Simon Roberts]

I work with a lot of people in classroom environments, trying to help them get started with Swagger, and I have to say that it's very difficult to get started with Swagger. Some examples with from-first-principles descriptions would probably help. The maven based build seems to hide a great deal of stuff that might be important, though since it's hidden, it's hard to tell.

Describing the parts, how they fit together, what's important for them to work together, would be good. The number of permutations surely adds to the difficulty of ab-initio understanding too.

Cheers,

Simon

[Ron]

Simon,

This is important feedback. We've been wanting to add an architecture documentation for Swagger-core, but the work load is huge and we don't seem to get around to it. I hope that for the next major release (together with Swagger 2.0) we'll be able to pull something together better.

We are working on generating a set-up guide for various combinations. Those should be published relatively soon.

As for maven - maven hides nothing with regards to the set up or configuration of the system. It's merely a way to bring in the required dependencies to use Swagger and has zero effect on its configuration.

--

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.

[Simon Roberts]

Well, the things that it "hides" are the secondary dependencies. For example, the simple swagger dependency brings in, or so it seems, jersey, servlet API, scala and logging (perhaps more). Sure, I accept that maven isn't hiding this in the sense of deliberate obfuscation, but the point of maven is that "you don't have to worry about it" -- except that you do, as I discovered when i tried to use one swagger dependency and include jersey myself. Because it was not obvious to me that I had two versions of jersey in the system at that point, it broke.

In other words, it's the "let me handle this for you" that hides things that you actually might need to know, or at least be aware of.

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/NzYwaOMGoP0/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
Simon Roberts

(303) 249 3613

[David Cramer]

Hi there,
I've come across this part of this thread through a search. I'd like to +1 Soonmok's comment, but do it in the correct place. However, I can't find another thread or forum where this is discussed. Is this the correct Google Group for discussing the Swagger 2.0 spec (understanding that this particular thread is about Swagger documentation)? If not, where does that discussion happen?

Regards,
David

[Alex Worden]

Perfect timing! I just posted a topic looking for help because the documentation falls short for me as a newcomer. 

Some suggestions:

a) Get a native English speaker to proof read your docs - it's very distracting to have syntactically-incorrect and grammatically-incorrect sentences. 

b) Organize the docs by use-case and coding language. I.e. I'm a Java developer looking to use swagger to expose my service API... what do I need to do / know. 

c) Explain how swagger works fundamentally. 

d) Add diagrams. Concepts that you guys take for granted are stumbling blocks for new comers. You can remove this hurdle when you lay out the concepts visually. 

Thanks,

Alex

[Ron]

The work on the Swagger 2.0 spec is pretty much done (and was done in a separate work group).

If you have any questions/comments, you can either create new threads here or open issues on https://github.com/wordnik/swagger-spec/.

[mlin...@thoughtworks.com]

On the site and github: I'd like a clearer indication of which tools, libraries and services support Swagger v2.

[Syed Raza Mehdi]

Hi Ron,

I am new to Swagger and what i did explored in Swagger so far is to make a JSON file and integrate it with Swagger UI and all that i explored all by myself or some help from the other platform. Now i was looking to make the JSON file with PHP and using swagger PHP but i couldn't find the appropriate help. The documentation provide on the site or the GIT HUB is so confusing and not well explained. 

Here is my suggestions.

 1) At first there is a brief explanation of what Swagger is with relation to different platforms.

 2) The documentation should provide step by step guideline with proper supporting images and sample codes.

 3) Rather than get the projects from so many different sections there should be one package where user can find what it want.

Thanks a lot.