4 ms·

Swagger: The World's Most Popular API Framework

29 points by based2 10y ago

howlett 10y 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".
royjacobs 10y 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 10y 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 https://github.com/zalando/connexion
- dahdum 10y 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.
raarts 10y ago
Does something like swagger exist for GraphQL?
- ruslan_talpa 10y ago
  yes, https://github.com/graphql/graphiql https://github.com/graphql/graphiql and it's better
  - ruslan_talpa 10y ago
    well, maybe graphiql is the equivalent of swaggerui but i figured you were actually looking for something like this

29 points by based2 10y 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".

royjacobs 10y 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 10y 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 https://github.com/zalando/connexion
dahdum 10y 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.

raarts 10y ago

Does something like swagger exist for GraphQL?

ruslan_talpa 10y ago
yes, https://github.com/graphql/graphiql https://github.com/graphql/graphiql and it's better
- ruslan_talpa 10y ago
  well, maybe graphiql is the equivalent of swaggerui but i figured you were actually looking for something like this