Documentation-driven development for APIs
1–10 of 15 posts
Re: Documentation-driven development for APIs
#2IMO something like Apiary [1] and running the blueprint as a mock server is even easier.
Re: Documentation-driven development for APIs
#3Perhaps "Specification-Driven Development" would be a better descriptor.
Re: Documentation-driven development for APIs
#4Fair, but it seems to be kind of an overkill for simple APIs, specially when it's internal APIs developed by a team that works well together.
Re: Documentation-driven development for APIs
#5At first I thought this might be doc-tests-for-REST.
Kinda disappointed. Doctests are nice. You should be able to doctest REST APIs.
Re: Documentation-driven development for APIs
#6At first I thought this might be doc-tests-for-REST. Kinda disappointed. Doctests are nice. You should be able to doctest REST APIs.
Tools like Postman make it really easy to write test scripts and automate other things around endpoints that are defined using OpenAPI, so you're pretty close once you have the OpenAPI spec written.
Re: Documentation-driven development for APIs
#7IMO something like Apiary [1] and running the blueprint as a mock server is even easier. [1] https://apiary.io/how-apiary-works
Apiary looks like it supports OpenAPI 3.0, so you get the best of both worlds. Having your API spec living in an open standard format also gives you the ability to easily write integration tests using other tools as well.
Re: Documentation-driven development for APIs
#8Fair, but it seems to be kind of an overkill for simple APIs, specially when it's internal APIs developed by a team that works well together.
I recently joined a company that builds all of its APIs this way, and I'm not looking back. It's so much easier to communicate across teams and tech stacks when we can send them a PR with a proposed endpoint contract. Plus, people always come and go and good API docs can help a new developer ramp up considerably faster.
Re: Documentation-driven development for APIs
#9A lot (although not all) of the advantages of the method given here are also advantages conferred by something strongly-typed like ASP.NET; quite a bit of the testing in the post seems to be there solely to make up for the fact that you can't specify the type of your output up front.
Re: Documentation-driven development for APIs
#10It would be great if the API specification could be written once and then consumed by both server and clients, not only for functional validation as shown in the article but also for the server to use the spec to validate and serialize inputs/outputs.
As described, there is a disconnect where you went to all the work to create the openapi oas.yaml file, and can feed that to your test client to ensure the API responds to that, but the API still had to be coded by hand to comply with the spec.
A way to feed the oas.yaml code to flask-smorest somehow so it derives the endpoints and schemas from that (hey it already makes a ton of assumptions about how to structure the application, requiring e.g. a set of methods named exactly as the endpoints so they can be easily matched) would make it so the single oas.yaml file drives both ends of the implementation, would make coding work easier as the schema doesn't need to be described multiple times in multiple languages/formats, and would provide quick feedback (FAILURES) if I change the schema without coding the required endpoint support.