This is an example for how you define the primary tag (like a category), a public/private tag, a sample request payload, a simple html table describing the request payload elements, and a simple table describing the response payload elements. (We'll be adding sample responses in the near future!)

Sample Payloads.xml

<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns:apigee="http://api.apigee.com/wadl/2010/07/" xmlns="http://wadl.dev.java.net/2009/02"xmlns:t="urn:simplegeo:simplegeoresponse"xsi:schemaLocation="http://wadl.dev.java.net/2009/02 http://apigee.com/schemas/wadl-schema.xsd http://api.apigee.com/wadl/2010/07/ http://apigee.com/schemas/apigee-wadl-extensions.xsd">
    <resources base="https://api.enterprise.apigee.com/v1">
        <!-- API Proxy-->
            <resource path="o/{org_name}/apis">
                <param name="baseurl" type="xsd:string" style="template" required="true"default="api.enterprise.apigee.com">
                    <doc>The top-level domain of the API</doc>
                </param>
                <param name="version" type="xsd:string" style="template" required="true" default="v1">
                    <doc>The version of the API</doc>
                </param>
                <param name="org_name" type="xsd:string" style="template" required="true">
                    <doc>A specific organization.</doc>
                </param>
                <method id="importApiProxy" name="POST" apigee:displayName="Import API Proxy">
                    <apigee:tags>
                        <apigee:tag primary="true">API Proxies</apigee:tag>
                    </apigee:tags>
                    <apigee:authentication required="true"/>
                    <apigee:example url="organizations/{org_name}/apis?action=import&amp;name={api_name}"/>
                    <doc apigee:url="http://apigee.com/docs/api/api_methods/24-import-an-api">
                        <![CDATA[<p>For detailed instructions on using the <i>Create an API proxy</i> method, see the <a href="http://apigee.com/docs/api/content/quickstarts/local-api-development">Developer Guide Topic</a> in the <a href="http://apigee.com/docs/enterprise/content/developer_guide">API Proxy Developer Guide</a>.</p>
                            <p>
                                <b>Overview:</b>
                            </p>
                            <p>This method creates an API proxy in an organization on the Apigee API Platform.</p>
                            <br/>
                            <p>The API proxy that is created using this call will not be accessible at runtime until the proxy is deployed to an environment. </p>
                            <br/>
                            <p>Usually, this request is followed up with an export API proxy method call, which exports the API proxy bundle to the developer's local machine for development.</p>
                            <br/>API proxies can also be created and deployed using the Apigee <a href="https://enterprise.apigee.com">Enterprise Management User Interface</a>.</p>]]>
                            </doc>
                            <request>
                                <param name="Content-Type" type="xsd:string" style="header" default="multipart/form-data"required="true">
                                <doc>Specify Content Type.</doc>
                            </param>
                            <param name="action" type="xsd:string" style="query" default="import" required="true">
                            <doc>Specify the action.</doc>
                        </param>
                        <param name="name" type="xsd:string" style="query" default="{api_name}" required="true">
                        <doc>Specify API name.</doc>
                    </param>
                    <representation mediaType="application/json">
                        <apigee:payload>
                            <doc>
                                <![CDATA[ <table class="table table-bordered">
                                    <thead>
                                        <tr>
                                            <th>Name</th>
                                            <th>Description</th>
                                        </tr>
                                    </thead>
                                    <tbody>
                                        <tr>
                                            <td>configurationVersion </td>
                                            <td>The version of Apigee that the configuration is valid for</td>
                                        </tr>
                                        <tr>
                                            <td>contextInfo </td>
                                            <td>Apigee generated contextual information about the entity</td>
                                        </tr>
                                        <tr>
                                            <td>name </td>
                                            <td>The name of the API</td>
                                        </tr>
                                    </tbody>
                                </table>]]>
                            </doc>
                            <apigee:content>
                                <![CDATA[{"name" : "myAPI"}]]>
                                </apigee:content>
                            </apigee:payload>
                        </representation>
                    </request>
                    <response>
                        <representation mediaType="application/json">
                            <apigee:payload>
                                <doc>
                                    <![CDATA[ <table class="table table-bordered">
                                        <thead>
                                            <tr>
                                                <th>Name</th>
                                                <th>Description</th>
                                            </tr>
                                        </thead>
                                        <tbody>
                                            <tr>
                                                <td>configurationVersion </td>
                                                <td>The version of Apigee that the configuration is valid for</td>
                                            </tr>
                                            <tr>
                                                <td>contextInfo </td>
                                                <td>Apigee generated contextual information about the entity</td>
                                            </tr>
                                            <tr>
                                                <td>name </td>
                                                <td>The name of the API</td>
                                            </tr>
                                            <tr>
                                                <td>policies </td>
                                                <td>Policies attached to the API </td>
                                            </tr>
                                            <tr>
                                                <td>proxyEndpoints </td>
                                                <td>Named proxy endpoints (receiver) defined for the API proxy</td>
                                            </tr>
                                            <tr>
                                                <td>resources </td>
                                                <td>Any code, scripts, XSLT files used by policies attached to this API</td>
                                            </tr>
                                            <tr>
                                                <td>revision </td>
                                                <td>The sequential numbered packages of code and configuration that make up an API proxy</td>
                                            </tr>
                                            <tr>
                                                <td>targetEndpoints </td>
                                                <td>Named proxy endpoints (sender) defined for the API proxy</td>
                                            </tr>
                                            <tr>
                                                <td>targetServers </td>
                                                <td>Target servers defined for load balancing purposes</td>
                                            </tr>
                                            <tr>
                                                <td>type </td>
                                                <td>Internal entity definition used by Apigee</td>
                                            </tr>
                                        </tbody>
                                    </table>
                                </table>]]>
                            </doc>
                        </apigee:payload>
                    </representation>
                </response>
            </method>
        </resource>
    </resources>
</application>