After looking at swagger (including openAPI in this), api-blueprint [1] and RAML, I've settled on api blueprint for writing documentation and even testing since it allows you to generate JSON schema from the structures you build up.
It does need a touch more work to allow re-usable fragments in get arguments and a couple of other areas, but it's certainly good enough for documenting and basic testing. There's still active development from apiary as far as I can tell and the MSOn syntax is really simple to become productive with.
Looks interesting. Seems like the seeds are being sown for fintech to take off with lot of big financial companies developing api's. for e.g:- https://developer.americanexpress.com/home
CapOne is definitely sailing ahead of others. How this benefits the company remains to be seen.
Hope this won't be like other companies (mint, twitter, etc) which opened up their api and shut them down or drastically reduced what dev's could do.
These are apples and cherry pits, apart from their coexistence on the HN front page right now. OpenAPI is basically Swagger + bigcorp buy-in, see https://openapis.org/. Whereas AMEX is offering a bespoke API straight out of 1998.
Modernization is an obvious benefit to banks. Anyone who's been in this industry talks about how many banks traditionally do not have good infrastructure or are ultimately buy everything remotely.
Capital One is changing that, we're building a lot of our own stuff. It's not an overnight process, but the results are pretty amazing internally and I hope it'll become more obvious externally soon.
It does need a touch more work to allow re-usable fragments in get arguments and a couple of other areas, but it's certainly good enough for documenting and basic testing. There's still active development from apiary as far as I can tell and the MSOn syntax is really simple to become productive with.
[1] https://apiblueprint.org/