XSLT to generate documentation from WADL

View: New views

3 Messages — Rating Filter: Alert me

XSLT to generate documentation from WADL

by Mark Nottingham-4 :: Rate this Message:

Reply to Author | View Threaded | Show Only this Message

Some parts of this message have been removed. Learn more about Nabble's security policy.

I've attached a stylesheet to generate HTML documentation from WADL
(latest revision; see <http://weblogs.java.net/blog/mhadley/archive/
2006/08/wadl_revision_1.html>), along with sample input and output.

I haven't tested it comprehensively, but I think it's good enough for
testing it as well as WADL itself, to see if we're onto something here.

Feedback very much welcome.

Yahoo News Search

Yahoo News Search

The News Search service allows you to search the Internet for news stories.

Resources

http://api.search.yahoo.com/NewsSearchService/V1/newsSearch

Representations
Faults

Resources

http://api.search.yahoo.com/NewsSearchService/V1/newsSearch

The News Search service is limited to 5,000 queries per IP address per day. See information on rate limiting and our Usage Policy to learn about acceptable uses and how to request additional queries

Sample Request Url: http://api.search.yahoo.com/NewsSearchService/V1/newsSearch?appid=YahooDemo&query=madonna&results=2&language=en

GET

Request

Query Parameters

parameter	value	description
appid	string (required)	The application ID. See Application IDs for more information.
query	string (required)	The query to search for.
type	string One of: `all` (default) `any` `phrase`	The kind of search to submit: all returns results with all query terms. any returns results with one or more of the query terms. phrase returns results containing the query terms as a phrase.
results	int Default: `10`	The number of results to return; at most, 50.
start	int Default: `1`	The starting result position to return (1-based). The finishing position (start + results - 1) cannot exceed 1000.
sort	string One of: `rank` (default) `date`	Sort articles by relevance or most-recent.
language	string	The language the results are written in. Supported Languages. Omitting language returns results in any language.
site	string	A domain to restrict your searches to (e.g. www.yahoo.com). You may submit up to 30 values (e.g., site=www.yahoo.com&site=www.cnn.com).
output	string One of: `xml` (default) `json` `php`	The format for the output. If json is requested, the results will be returned in JSON format. If php is requested, the results will be returned in Serialized PHP format.
callback	string	The name of the callback function to wrap around the JSON data. The following characters are allowed: A-Z a-z 0-9 . [] and _. If output=json has not been requested, this parameter has no effect. More information on the callback can be found in the Yahoo! Developer Network JSON Documentation.

Response

Response Representations

News Search Result Set (application/xml)

Faults

400 - application/xml

Representations

News Search Result Set (application/xml)

XML Schema

Source: http://api.search.yahoo.com/NewsSearchService/V1/NewsSearchResponse.xsd

<xs:element name="ResultSet">
		<xs:complexType>
			<xs:sequence>
				<xs:element name="Result" type="ResultType" minOccurs="0" maxOccurs="50"/>
			</xs:sequence>
			<xs:attribute name="totalResultsAvailable" type="xs:integer"/>
			<xs:attribute name="totalResultsReturned" type="xs:integer"/>
			<xs:attribute name="firstResultPosition" type="xs:integer"/>
		</xs:complexType>
	</xs:element>

Representation Parameters

parameter	value	description
ResultSet		Contains all of the query responses. Has attributes: totalResultsAvailable: The number of query matches in the database. totalResultsReturned: The number of query matches returned. This may be lower than the number of results requested if there were fewer total results available. firstResultPosition: The position of the first result in the overall search.
Result		Contains each individual response.
Title		The title of the article.
Summary		Summary text associated with the article.
Url		The URL for the article.
ClickUrl		The URL for linking to the article. See URL linking for more information.
NewsSource		The company that distributed the news article, such as API or BBC.
NewsSourceUrl		The URL for the news source.
Language		The language the article is written in.
PublishDate		The date the article was first published, in unix timestamp format.
ModificationDate		The date the article was last modified, in unix timestamp format.
Thumbnail		The URL of a thumbnail file associated with the article, if present, and its height and width in pixels.

Faults

400 - application/xml

See the Standard Error documentation.

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="wadl_documentation.xsl"?>
<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://research.sun.com/wadl wadl.xsd"
xmlns:tns="urn:yahoo:yn"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:yn="urn:yahoo:yn"
xmlns:ya="urn:yahoo:api"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns="http://research.sun.com/wadl/2006/07">

<doc title="Yahoo News Search">
The News Search service allows you to search the Internet for news stories.
</doc>

<grammars>
<include
href="http://api.search.yahoo.com/NewsSearchService/V1/NewsSearchResponse.xsd"/>
</grammars>

<resources base="http://api.search.yahoo.com/NewsSearchService/V1/">
<resource path="newsSearch">
<doc>
<html:p>The News Search service is limited to 5,000 queries per IP address per day. See information on <html:a href="http://developer.yahoo.com/search/rate.html">rate limiting</html:a> and our <html:a href="http://developer.yahoo.com/usagePolicy/">Usage Policy</html:a> to learn about acceptable uses and how to request additional queries</html:p>
<html:p>Sample Request Url: <html:a href="http://api.search.yahoo.com/NewsSearchService/V1/newsSearch?appid=YahooDemo&query=madonna&results=2&language=en">http://api.search.yahoo.com/NewsSearchService/V1/newsSearch?appid=YahooDemo&query=madonna&results=2&language=en</html:a></html:p>
</doc>
<method name="GET" id="search">
<request>
<param name="appid" type="xsd:string" required="true">
<doc>The application ID. See <html:a href="http://developer.yahoo.com/faq/index.html#appid">Application IDs</html:a> for more information.</doc>
</param>
<param name="query" type="xsd:string" required="true">
<doc>The query to search for.</doc>
</param>
<param name="type" type="xsd:string" default="all">
<doc><html:p>The kind of search to submit:</html:p>
<html:ul>
<html:li><html:em>all</html:em> returns results with all query terms.</html:li>
<html:li><html:em>any</html:em> returns results with one or more of the query terms.</html:li>
<html:li><html:em>phrase</html:em> returns results containing the query terms as a phrase.</html:li>
</html:ul>
</doc>
<option value="all"/>
<option value="any"/>
<option value="phrase"/>
</param>
<param name="results" type="xsd:int" default="10">
<doc>The number of results to return; at most, 50.</doc>
</param>
<param name="start" type="xsd:int" default="1">
<doc>The starting result position to return (1-based). The finishing position (start + results - 1) cannot exceed 1000.</doc>
</param>
<param name="sort" type="xsd:string" default="rank">
<doc>Sort articles by relevance or most-recent.</doc>
<option value="rank"/>
<option value="date"/>
</param>
<param name="language" type="xsd:string">
<doc>The language the results are written in. <html:a href="http://developer.yahoo.com/search/languages.html">Supported Languages</html:a>. Omitting language returns results in any language.</doc>
</param>
<param name="site" type="xsd:string">
<doc>A domain to restrict your searches to (e.g. www.yahoo.com). You may submit up to 30 values (e.g., site=www.yahoo.com&site=www.cnn.com).</doc>
</param>
<param name="output" type="xsd:string" default="xml">
<doc>The format for the output. If <html:em>json</html:em> is requested, the results will be returned in <html:a href="http://developer.yahoo.com/common/json.html">JSON</html:a> format. If <html:em>php</html:em> is requested, the results will be returned in <html:a href="http://developer.yahoo.com/common/phpserial.html">Serialized PHP</html:a> format.</doc>
<option value="xml"/>
<option value="json"/>
<option value="php"/>
</param>
<param name="callback" type="xsd:string">
<doc>The name of the callback function to wrap around the JSON data. The following characters are allowed: A-Z a-z 0-9 . [] and _. If output=json has not been requested, this parameter has no effect. More information on the callback can be found in the <html:a href="http://developer.yahoo.com/common/json.html#callbackparam">Yahoo! Developer Network JSON Documentation</html:a>.</doc>
</param>
</request>
<response>
<representation mediaType="application/xml" element="yn:ResultSet">
<doc title="News Search Result Set"></doc>
<param name="ResultSet">
<doc><html:p>Contains all of the query responses. Has attributes:</html:p>
<html:ul>
<html:li><html:b>totalResultsAvailable</html:b>: The number of query matches in the database.</html:li>
<html:li><html:b>totalResultsReturned</html:b>: The number of query matches returned. This may be lower than the number of results requested if there were fewer total results available.</html:li>
<html:li><html:b>firstResultPosition</html:b>: The position of the first result in the overall search.</html:li>
</html:ul>
</doc>
</param>
<param name="Result">
<doc>Contains each individual response.</doc>
</param>
<param name="Title">
<doc>The title of the article.</doc>
</param>
<param name="Summary">
<doc>Summary text associated with the article.</doc>
</param>
<param name="Url">
<doc>The URL for the article.</doc>
</param>
<param name="ClickUrl">
<doc>The URL for linking to the article. See <html:a href="http://developer.yahoo.com/faq/index.html#clickurl">URL</html:a> linking for more information.</doc>
</param>
<param name="NewsSource">
<doc>The company that distributed the news article, such as API or BBC.</doc>
</param>
<param name="NewsSourceUrl">
<doc>The URL for the news source.</doc>
</param>
<param name="Language">
<doc>The language the article is written in.</doc>
</param>
<param name="PublishDate">
<doc>The date the article was first published, in <html:a href="http://en.wikipedia.org/wiki/Unix_time">unix timestamp</html:a> format.</doc>
</param>
<param name="ModificationDate">
<doc>The date the article was last modified, in <html:a href="http://en.wikipedia.org/wiki/Unix_time">unix timestamp</html:a> format.</doc>
</param>
<param name="Thumbnail">
<doc>The URL of a thumbnail file associated with the article, if present, and its height and width in pixels.</doc>
</param>
</representation>
<fault id="yaError" status="400" mediaType="application/xml">
<doc>See the <html:a href="http://developer.yahoo.com/search/errors.html">Standard Error documentation</html:a>.</doc>
</fault>
</response>
</method>
</resource>
</resources>
</application>

--
Mark Nottingham
mnot@...

wadl_documentation.xsl (27K) Download Attachment

Re: XSLT to generate documentation from WADL

by Mark Nottingham-4 :: Rate this Message:

Reply to Author | View Threaded | Show Only this Message

Thanks. I was intending to put it on a Web site, because I've already
updated it, so:
http://www.mnot.net/webdesc/

Cheers,

On 2006/08/08, at 10:37 AM, Jerome Louvel wrote:

>
> Hi Mark,
>
> This looks great! Maybe it would be useful to setup a Web page for
> this
> stylesheet. We could easily point people to it, keep track of
> updates, send
> comments, etc.
>
> I'm planning to support WADL in the Restlet project, and generating
> nice
> documentation based on your XSLT will be very cool. See
> http://restlet.tigris.org/issues/show_bug.cgi?id=59
>
> Best regards,
>
> Jerome Louvel
> http://www.restlet.org
>
>> -----Message d'origine-----
>> De : public-web-http-desc-request@...
>> [mailto:public-web-http-desc-request@...] De la part de
>> Mark Nottingham
>> Envoyé : jeudi 3 août 2006 20:11
>> À : public-web-http-desc@...
>> Objet : XSLT to generate documentation from WADL
>>
>> I've attached a stylesheet to generate HTML documentation from WADL
>> (latest revision; see <http://weblogs.java.net/blog/mhadley/archive/
>> 2006/08/wadl_revision_1.html>), along with sample input and output.
>>
>> I haven't tested it comprehensively, but I think it's good
>> enough for
>> testing it as well as WADL itself, to see if we're onto
>> something here.
>>
>> Feedback very much welcome.
>>
>>
>>
>>
>>
>
>
>

--
Mark Nottingham
mnot@...

Re: XSLT to generate documentation from WADL

by Mark Nottingham-4 :: Rate this Message:

Reply to Author | View Threaded | Show Only this Message

I've made a very small update to link to simple types as well as
elements, and to link from parameter types as well.

Additionally, I've started writing a .xsd for URI component types, so
that there's something better than xs:string for path segments, etc.

http://www.mnot.net/webdesc/

Comments welcome.

--
Mark Nottingham
mnot@...