So,
At two levels, there is plenty of markup you can add.
In Schema:
Your wsdl file will either import or include one or more schemas, or
have the types defined in-situ. But in general, in XML schema you can
add the annotation element. Here is a silly example:
<xsd:schema xmlns:xs="http://www.w3.org/2001/XMLSchema";
xmlns:doc="http://some.org/doc";
<xs:element name="AuthContext">
<xs:annotation>
<xs:documentation xml:lang="en"
source="http://some.org/some.product";>
<doc:description>The authentication context. This is a top level
construct used to supply ontext.</doc:description>
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element name="blah" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
The anotation element can have an AppInfo tag as well. Best to look up
annotations at the w3 site and read about it.
In WSDL file:
In wsdl files you can place this kind of thing just about anywhere, I
think:
<wsdl:documentation>
<wsi:Claim conformsTo="http://ws-i.org/profiles/basic1.1/"/>
Free text here, too ???
</wsdl:documentation>
I believe you can have free-flowing text as well. Again, best to check
the real WSDL spec to make sure.
-----------------------------
There are tools that parse for this kind of markup (especially the XML
Schema example above), but I can't think of any right now. Do a google
search on xml parsers, I'm sure something will turn up.
-jeff
-----Original Message-----
From: Michael Potter [mailto:[EMAIL PROTECTED]
Sent: Tuesday, August 07, 2007 3:51 PM
To: [email protected]
Subject: webservices documentation for non-technical users
Axis2 list,
I have a need to document our webservices in a format usable by
non-technical users.
What I have in mind is some additional markup in my .wsdl files that I
will filter and use to generate .pdf files. This would be done in the
spirit of javadoc for java and pod for perl.
My questions are:
1) Has anyone already done such a thing?
2) Is there a standard way to do that?
There is specific markup that allows one to specify maximum field
sizes in .wsdl. Also, there is mark up to specify comments.
3) Can anyone comment on the use of those features, specifically: do
they "get in the way" of other tools?
--
Michael Potter
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
