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.