Open jmmercadom opened 11 years ago
:-1
doing a yaml representation of json-schema seems silly. i'm also hoping the format will stay pretty portable. json-schema is supported by multiple programming languages.
i think a more worthwhile enhancement would be something to help generate contracts from sample data. check out https://github.com/perenecabuto/json_schema_generator/blob/master/USAGE.md for some inspiration
We are beginning to use Pacto on our current project and we got to the same conclusion, writing json schemas by hand is a big pain and it seems to be easy to generate the schema from a sample.
Lots of apis have samples of their return json somewhere on their documentation, so using plain json can help a lot the initial adoption of contracts, and is also much easier to read =) Going to implement that soon.
Take a look at http://apiblueprint.org/
A friend just pointed me to http://orderly-json.org/docs. On a first glance it looks very promising, although is has not been maintained for quite a while. I haven't really looked in detail yet, but thought it would be worth sharing. Thoughts?
Another really nice approach to the same problem (note that they're using YAML): https://github.com/square/fdoc
I'm not sure why I said YAML was silly. The only thing I can think is - if it's just an alternate format for the same schema, then :+1:. If it's a different schema, then :-1:.
I'll assume it's just support for loading the same schema. This has some benefits and is pretty easy to implement. Benefits:
There are some additional changes I'd proposed, but I suggest closing this issue once YAML support is added, and creating a new issue for "Proposal: Contract Format 2.0" issue.
Another format to check out. It's "heavily inspired by Swagger", not sure what the differences are from Swagger as json.
http://guzzle.readthedocs.org/en/latest/webservice-client/guzzle-service-descriptions.html
A lot of it looks pretty interesting, but some things are more complex than I'd want to support (initially).
I'm going to go with Swagger 2.0. The current Swagger was pretty close to what I wanted, but I was worried it wouldn't quite address my needs. Now there's an active working group for Swagger 2.0 which is trying to make Swagger even better. I've joined the working group but haven't made any contributions yet.
The reasons I feel Swagger is the right choice:
Now, we won't be able to switch to swagger overnight. My plan is simply to start making Pacto more swagger-esque, with the eventual goal of Swagger compatibility.
Any objections?
FYI - samples and schemas for Swagger 2.0 are at: https://github.com/reverb/swagger-spec
If I haven't sold you yet, read this: https://blog.apigee.com/detail/a_design_first_approach_to_building_apis_with_swagger
The specification (of a contract) right now is very verbose. For anything non-trivial, the specification is basically non-human readable. We could use the yaml representation of json-schema as that is more compact and then write a simple DSL that represents the request-response bits and keep the structure of the actual response body still in yaml representation of json schema.