Swagger: The World's Most Popular API Framework

by based2 • 9 years ago

29 7 9 years ago

royjacobs• 9 years ago

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• 9 years ago

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

dahdum• 9 years ago

I like starting with Swagger as the design tool for a new API, but I haven't done any generation directly. I implement as defined and let the json get generated by reflection to serve as documentation.

howlett• 9 years ago

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• 9 years ago

Does something like swagger exist for GraphQL?

ruslan_talpa2• 9 years ago

yes, https://github.com/graphql/graphiql and it's better

ruslan_talpa2• 9 years ago

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

Swagger: The World's Most Popular API Framework

Related Stories