Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Fix formatting^2

  • Loading branch information...
commit 7693df5a7cab6f46b6e99b934b48fc57a6cc86a0 1 parent 328e530
@Baggz Baggz authored
Showing with 10 additions and 10 deletions.
  1. +10 −10 _posts/2013-10-10-No-more-outdated-API-documentation.md
View
20 _posts/2013-10-10-No-more-outdated-API-documentation.md
@@ -7,29 +7,29 @@ author: netmilk
published: YES
---
-Your API is only as good as its documentation. API Documentation is a must for any public API and a need for you private APIs. To have always valid documentation is a holy grail for any API owner. That is why I'm very excited to announce the release of the **[Dredd][] command-line test runner for [API Blueprint][]**.
+Your API is only as good as its documentation. API Documentation is a must for any public API and a need for you private APIs. To have always valid documentation is a holy grail for any API owner. That is why I'm very excited to announce the release of the **[Dredd][] command-line test runner for [API Blueprint][]**.
![Dredd](http://blog.apiary.io/images/Dredd.png?1)
-# Write blueprints!
+## Write blueprints!
-OK, we want the always up-to-date documentation. What would be the first thought? Why not generate an API documentation from the code? **Naughty, naughty! Bad idea!**
+OK, we want the always up-to-date documentation. What would be the first thought? Why not generate an API documentation from the code? **Naughty, naughty! Bad idea!**
Write a blueprint! When you generate docs from the code you are creating ad-hoc rules inferred from code, without actually getting any valuable feedback. Don't be arrogant when you can be generous.
-API Blueprint is a contract with the consumers of your API. You can publicize or even open-source your API Blueprint and boldly invite anybody to the design process of your API. That backend guy, your frontend coder, mobile developers and your customers in the first place. They don't need and often don't want to know what's under the hood. API Blueprint is a language agnostic, human readable format to discuss things about web APIs.
+API Blueprint is a contract with the consumers of your API. You can publicize or even open-source your API Blueprint and boldly invite anybody to the design process of your API. That backend guy, your frontend coder, mobile developers and your customers in the first place. They don't need and often don't want to know what's under the hood. API Blueprint is a language agnostic, human readable format to discuss things about web APIs.
-You don't need to know anything about programming to contribute to the discussion. Don't hesitate to invite even your UI designer to the table. He or she will surely feel comfortable at the table, and believe me, you will definitely get some spot-on comments. Simply because this approach is natural in the non-development environments.
+You don't need to know anything about programming to contribute to the discussion. Don't hesitate to invite even your UI designer to the table. He or she will surely feel comfortable at the table, and believe me, you will definitely get some spot-on comments. Simply because this approach is natural in the non-development environments.
Writing API Blueprint is like making wireframes. Wireframes are often called mocks, aren't they? Don't be surprised, [Apiary][] will generate a working mock server from your API blueprint. It means **you can start hacking against your future API** immediately.
-Can you imagine this open discussion with your `/app/controllers` folder on the table?!? Do you feel how open the philosophy of API Blueprint and Apiary is? The iterative collaboration around API Blueprint ensures the best possible feedback and API design. It lets you create beautiful APIs which are truly consumable and competitive.
+Can you imagine this open discussion with your `/app/controllers` folder on the table?!? Do you feel how open the philosophy of API Blueprint and Apiary is? The iterative collaboration around API Blueprint ensures the best possible feedback and API design. It lets you create beautiful APIs which are truly consumable and competitive.
-# Let Dredd test your documentation
+## Let Dredd test your documentation
-I have promised always up-to-date API documentation. You might think that to not generate documentation from the code and thus decoupling the API documentation from the implementation is unnecessary overhead. But it is not. Here comes [Dredd][].
+I have promised always up-to-date API documentation. You might think that to not generate documentation from the code and thus decoupling the API documentation from the implementation is unnecessary overhead. But it is not. Here comes [Dredd][].
-Dredd is a command-line test runner for testing of your backend API application on the HTTP layer. **Dredd enables documentation-driven development and test-driven development of your APIs.**
+Dredd is a command-line test runner for testing of your backend API application on the HTTP layer. **Dredd enables documentation-driven development and test-driven development of your APIs.**
$ npm install -g dredd
$ dredd ./apiary.apib http://localhost:3000
@@ -40,7 +40,7 @@ Dredd is a command-line test runner for testing of your backend API application
0
-Testing API Blueprint amplifies the contract benefits. When you negotiate a change in the contract tests will fail until your implementation is in accordance with the documentation. Similarly, should you rename a key in an HTTP response JSON you have to discuss it with the contract to make the tests pass.
+Testing API Blueprint amplifies the contract benefits. When you negotiate a change in the contract tests will fail until your implementation is in accordance with the documentation. Similarly, should you rename a key in an HTTP response JSON you have to discuss it with the contract to make the tests pass.
[Apiary]: http://apiary.io
Please sign in to comment.
Something went wrong with that request. Please try again.