Beschrijven web service / SOAP

[Verwijderd]

Ik heb me de afgelopen dagen hier op werk bezig gehouden met het ontwikkelen van een paar web services, die straks door een externe partij gebruikt gaan worden.

De aanroep van deze webservices vereist nogal wat uitleg naar die externe partij toe (Veldbeschrijving, lengte, restricties) etc.

Dus ik wilde een mooi documentje gaan schrijven die tot in detail uitlegt hoe onze web services 'geconsumeerd' mogen worden.

Ik vroeg me af of er voor dit specifieke doel al bestaande methodieken / programma's zijn?

Heeft iemand ervaring met het documenteren van dit soort zaken? Ik kan wel een mooi Word document gaan schrijven, maar wellicht is er een betere oplossing?

[P_de_B]

[Google=wsdl]

[LordLarry]

Dat zit toch allemaal in de wsdl als het goed is? En in .Net kan je attributes toevoegen met commentaar zodat men dat gewoon kan lezen als ze naar je webservice browsen. Of heb je het niet gemaakt in .Net?

[Verwijderd]

Ik begrijp heel goed dat de WSDL een mooie beschrijving van de velden geeft. Ik zocht meer naar een methodiek om aan te kunnen geven wat ik verwacht dat men met die velden doet. Je hebt bijvoorbeeld een veld 'invoice_address'.

Ik wil in 'normale mensen' taal kunnen beschrijven dat ik hier het faktuur adres verwacht, en dat ik verwacht dat dit veld maximaal 50 tekens lang is. Verder wil ik kunnen beschrijven welke exceptions er kunnen optreden en wanneer.

Nogmaals: Dit kan ik natuurlijk in een Word document doen, maar ik vroeg me af of er een standaard is?

[Verwijderd]

Het is overigens geen .NET web service, maar een ColdFusion web service. Ik heb tot op heden geen manier gevonden om hiermee commentaar mee te geven aan de velden. Als dat zou kunnen zou ik al blij zijn

[whoami]

Kan je in je WSDL file geen comment oid toevoegen?

[Verwijderd]

De WSDL wordt door de ColdFusion server automatisch gegenereerd, dus daar kan ik niet zomaar comments aan gaan toevoegen.

In een ideale situatie zat ik te denken aan een tooltje dat mijn WSDL inleest, en een mooi Word documentje uitpoept oid.