5 ms·

There's also the swagger spec: http://swagger.io/ http://swagger.io/

by jwingy 11y ago

gsibble 11y ago
I have used swagger in multiple projects with great success.
- Abundnce10 11y ago
  Are any of those projects open source? I'm looking for an example Swagger YAML/JSON file that includes authentication.
  - sarnowski 11y ago
    https://github.com/zalando-stups/pierone/blob/master/resources/api/pierone-api.yaml https://github.com/zalando-stups/pierone/blob/master/resourc... PierOne is a Docker registry in Clojure with S3 backend and OAuth support. I wrote swagger1st[0] which is used there. Swagger supports authorization definitions via scopes. Besides that, you can only define required basic auth or API key usage for authentication but not for authorisation. Swagger defines various places, where you can add own x-* attributes to fill in your own logic if swagger is not expressive enough. [0] https://github.com/sarnowski/swagger1st https://github.com/sarnowski/swagger1st
    - Abundnce10 11y ago
      Awesome. Thanks for sharing!
joesmo 11y ago
Swagger has a lot more backing / support amongst API proxy providers as well.
andrewstuart 11y ago
This might be of interest - generates Python/Falcon API server from Swagger spec. https://github.com/crowdwave/serve_swagger https://github.com/crowdwave/serve_swagger
jzsprague 11y ago
i used to use raml and still actually prefer it to swagger, but find that swagger is much more widely supported.
rlevy 11y ago
Swagger seems to have more awareness and adoption but we have fully embraced RAML due to its "composability" features which eliminate much of the boilerplate and copy/paste/tweak required by Swagger. Making the API spec easier to author & maintain is well worth the downsides of not being able to tap into the Swagger ecosystem. If we really needed something from the Swagger ecosystem, I don't think it would be difficult to create a RAML->Swagger converter. There is already a converter that goes the other direction. But whichever one you choose, this stuff is awesome. We author API specs and then codegen mock services, client side wrappers (Angular services or Backbone models/collections), server side DTOs and controllers, and pretty documentation. Having that all done from a single authoritative text file under source control has drastically reduced the friction between frontend and backend developers.

There's also the swagger spec: http://swagger.io/ http://swagger.io/

by jwingy 11y ago

There's also the swagger spec: http://swagger.io/ http://swagger.io/

gsibble 11y ago

I have used swagger in multiple projects with great success.

Abundnce10 11y ago
Are any of those projects open source? I'm looking for an example Swagger YAML/JSON file that includes authentication.
- sarnowski 11y ago
  https://github.com/zalando-stups/pierone/blob/master/resources/api/pierone-api.yaml https://github.com/zalando-stups/pierone/blob/master/resourc... PierOne is a Docker registry in Clojure with S3 backend and OAuth support. I wrote swagger1st[0] which is used there. Swagger supports authorization definitions via scopes. Besides that, you can only define required basic auth or API key usage for authentication but not for authorisation. Swagger defines various places, where you can add own x-* attributes to fill in your own logic if swagger is not expressive enough. [0] https://github.com/sarnowski/swagger1st https://github.com/sarnowski/swagger1st
  - Abundnce10 11y ago
    Awesome. Thanks for sharing!

joesmo 11y ago

Swagger has a lot more backing / support amongst API proxy providers as well.

andrewstuart 11y ago

This might be of interest - generates Python/Falcon API server from Swagger spec. https://github.com/crowdwave/serve_swagger https://github.com/crowdwave/serve_swagger

jzsprague 11y ago

i used to use raml and still actually prefer it to swagger, but find that swagger is much more widely supported.

rlevy 11y ago

Swagger seems to have more awareness and adoption but we have fully embraced RAML due to its "composability" features which eliminate much of the boilerplate and copy/paste/tweak required by Swagger. Making the API spec easier to author & maintain is well worth the downsides of not being able to tap into the Swagger ecosystem. If we really needed something from the Swagger ecosystem, I don't think it would be difficult to create a RAML->Swagger converter. There is already a converter that goes the other direction. But whichever one you choose, this stuff is awesome. We author API specs and then codegen mock services, client side wrappers (Angular services or Backbone models/collections), server side DTOs and controllers, and pretty documentation. Having that all done from a single authoritative text file under source control has drastically reduced the friction between frontend and backend developers.