
Swagger: The World's Most Popular API Framework - based2
http://swagger.io/
======
royjacobs
I'm interested to hear about people's opinion of Swagger (OpenAPI) or RAML or
anything else with regards to doing API-first designs.

In a lot of cases I see Swagger.json files being generated by reflecting over
the actual code, but I seldom hear from people manually writing
specifications.

I believe this can be very interesting since it allows you to centralize
documentation, generate protocol-agnostic clients to share with other teams in
your organisation, etc.

RAML seems to have more support for extensibility (i.e. annotating API
endpoints with custom parameters that are not in the official spec) though.
Not sure if OpenAPI 3.0 has more support for that, too.

~~~
nicolaslem
I often write swagger files that are fed to a library[0] that maps them to
Flask endpoints and does input validation.

Writing the schema is always a painful experience. I find the result overly
verbose and not human friendly. Which makes me think that these things
shouldn't be hand crafted.

> I believe this can be very interesting since it allows you to centralize
> documentation, generate protocol-agnostic clients to share with other teams
> in your organisation, etc.

On the paper yes, but I have yet to come across formal API specification used
this way. The only usage I see in the wild is the generation of web API
browsers, a la swagger UI.

[0]
[https://github.com/zalando/connexion](https://github.com/zalando/connexion)

------
howlett
I've used swagger quite a lot the last couple of years but I have a problem
which I still haven't found an elegant solution for.

How can I self host the API documentation (as reference) without setting up
the whole UI? Everything I've tried is "experimental", "not tested" and
"almost working".

------
raarts
Does something like swagger exist for GraphQL?

~~~
ruslan_talpa
yes,
[https://github.com/graphql/graphiql](https://github.com/graphql/graphiql) and
it's better

~~~
ruslan_talpa
well, maybe graphiql is the equivalent of swaggerui but i figured you were
actually looking for something like this

