Proposal: Categories and tags for Swagger projects

I've got a proposal for categorizing the available Swagger tools and libraries. Technically I guess that content is part of swagger-spec's README right now, but I think it makes sense to discuss it here because:

1. Most people will find it the link on swagger.io
2. It probably makes sense to move that content to swagger.io, especially if you want a more advanced list (like the MiddlemanApp directory, which as tags like "Official" vs "Community" and supports searching and filtering)

In answer on quora related to WADL, but noting that Swagger serves a similar purpose, Gregory Brail of Apigee wrote that it could be used to:

• Generate readable, good-looking documentation
• Present an easy-to-use API test console
• Automatically generate test cases
• Automatically generate a client-side SDK

He also wrote:

Otherwise, the only way for a tool do to these things is to introspect the source.

I think that's a pretty good start for thinking about how to categorize the existing Additional Libraries for Swagger. The last statement about "introspecting the source" isn't a use for swagger itself but is a characteristic of some Swagger libraries/tools: projects that introspect source in order to generate a Swagger contract. Basically a code generator in reverse - or a "Swagger generator".

In the long run I think tagging libraries will work better than listing, so I'd propose these tags for libraries/tools that are similar to the categories above:

• Documentation
• API Console
• Testing
• Code generator
• Swagger generator

Perhaps API Console is a subcategory of documentation. It may also make sense to have "Parser" and/or "Validator", which seem to be the common categories for the lower-level libraries.

Additionally it makes sense to tag things by:

• Supported Swagger version(s)
• Interface (e.g. Programming language)

I wrote interface rather than programming language because people may be more interested in how than can talk to a library than how it was implemented. In most cases that's through the language (Ruby, JavaScript, etc), but sometimes its a common interface for a family of languages (.NET CLR, JVM) and other times it might be a language-agnostic interface (e.g. "HTTP" for projects that just launch a stub server for an API, or "CLI" for projects like signalfx/swagger-cli-client).

So, for example, we might associate metadata like this with a project:

flask-restful-swagger:
  categories:
    - Swagger generator
  interface:
    - Python
  swagger_support:
    - 2.0
    - 1.2

Review the swagger-spec README section linked as “Additional Libraries” and the proposed swagger.io destination. First determine whether the work is a content move or a searchable, tagged directory; done requires an agreed taxonomy and metadata scope for the listed Swagger tools and libraries.