Documenting Web API

A long time ago when SOAP was ubiquitous, WSDL was the only way to document your API.

There were two approaches - code first approach, and contract first approach. With code first approach you first develop your service and then with the help of library wsdl got generated. When you use contract first approach you develop WSDL description of your service and then code the service.

Now everyone doing REST. To document the service one could use RAML or swagger annotations. I have not used RAML, but I have used swagger. With swagger one can also use one of two approaches. Using swagger annotations were like a breeze. Now a good news. Swagger has been bought by SmartBear and renamed to OpenAPI Specification.
Now instead of swagger annotations we can use OpenAPI annotations.
With maven swagger plugin one can generate the specification during compilation time. Also there are plugins so that specification can be generated and accessed at runtime.
Apart from that new tools started to apper to work with OpenAPI specifications: editors, validators, report generators and so on. You can check https://openapi.tools for a list of tools.

There is a good introductory book to OpenAPI specification: The Design of Web APIs by Arnaud Lauret.
I specifically recommend reading chapters 4 and 12. Chapter 4 tells you how to create specification, chapter 12 tells about producing reports from the specification.

Tricky Swagger

Hello.
I was faced with a task to create a documentation for our new developing REST service. Search revealed two technologies at hand: JSON-WSP and Swagger.
I liked more Swagger,  because:
1) I can dynamically define documentation with annotations in java
2) relatively simple syntax allows to define the documentation by hand
3) there is a good application Swagger UI which allows to explore the service documentation and more important play with your api.

So here are some tricky moments I was faced during the development of specification and using Swagger UI:
1) If you use Swagger UI with documents other than English then you have to insert into Swagger UI index file the meta 'Content-Type' tag.
2) For your convenience set the 'discoveryUrl' in Swagger UI to your resource listing file.
3) When developing the documentation by hand check your json with validators like http://jsonlint.com/. Because errors in Swagger UI are not displayed.
4) When defining parameters in spec you can use path, query, body, or header AND form. The latter allows you to send json into multipart request. The 'form' argument is not mentioned  in https://github.com/wordnik/swagger-core/wiki/Parameters.
5) When defining you api you should point out the 'responseClass'. If you want your method to return an array of objects you can use the following construction: responseClass: 'List[Item]', where Item is your domain model. This moment is not well documented in documentation.

That's all for now.