4 ms·
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 Sw
by 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 agoI 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 agoI 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.