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.
