Hi developers;
I'm investigating documenting Web services for an upcoming solution. I'm told we have a WSDL and eventually maybe also a Java API. I have experience documenting Java SDKs way in the past but have not yet worked with Web services. I expected there to be a tool similar to Javadoc that helps you document directly in the code, then extracts the documentation neatly into an HTML-based documentation set.
I've pinged many SAP Mentors on Twitter but I haven't found a tool yet -- or a best practice. My question -
1 - Do you know a good tool that helps document Web services?
I've tried a couple of proprietary tools but I'm not yet impressed. In addition, Matthias Steiner pointed me to enunciate and I hope to check that out soon; Google's WSDL viewer seems like it might be complicated (I haven't worked with XLST)
2 - Can you point me to some great examples of Web services API docs? For example ...
- Flickr http://www.flickr.com/services/api/
- Amazon http://aws.amazon.com/documentation/
- LinkedIn http://developers.linkedin.com/apis
Bonus points if you know tools used to create the respective documentation. I've got to think it's more than just hand-created HTML.
3 - As a Web service developer, how do you like to work? do you expect a well-documented WSDL online or do you look to a set of downloadable PDFs or Word docs, or other?
thanks in advance for any insights.
-m