org.codehaus.enunciate.modules.docs.docs.xml.fmt Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of enunciate-docs Show documentation
The Enunciate docs module generates the Web service interface documentation.
There is a newer version: 1.31
[#ftl]
[#-- @ftlvariable name="resources" type="java.util.Collection<org.codehaus.enunciate.contract.jaxrs.ResourceMethod>" --]
[#-- @ftlvariable name="wsdl" type="org.codehaus.enunciate.config.WsdlInfo" --]
[#-- @ftlvariable name="schema" type="org.codehaus.enunciate.config.SchemaInfo" --]
[@file name="docs.xml" charset="utf-8"]
<?xml version="1.0" encoding="UTF-8"?>
<api-docs[#if copyright??] copyright="${copyright?xml}"[/#if][#if licenseFile??] licenseFile="${licenseFile}"[/#if][#if title??] title="${title?xml}"[/#if]>
[#if apiDoc??]
  <documentation>
    <![CDATA[${apiDoc}]]>
  </documentation>
  [#list apiDoc?keys as tag]
    [#list apiDoc[tag] as tagValue]
  <tag name="${tag}"><![CDATA[${tagValue}]]></tag>
    [/#list]
  [/#list]
[/#if]
  <data>
[@forEachSchema]
  [#if (schema.typeDefinitions?size > 0) || (schema.globalElements?size > 0)]
    <schema namespace="${schema.namespace!""}" namespaceId="${schema.id}"[#if schema.properties.filename??] file="${schema.properties.filename}"[/#if]>
      <types>
    [#list schema.typeDefinitions as type]
      [#if !isFacetExcluded(type)]
        <type name="${type.name!"(anonymous)"}" id="${type.qualifiedName}" package="${type.package.qualifiedName}"[#if !type.baseObject] extendsType="${type.superclass.declaration.qualifiedName}"[/#if]>
        [#if type.docValue??]
          <documentation>
            <![CDATA[${type.docValue}]]>
          </documentation>
        [/#if]
        [#list type.javaDoc?keys as tag]
          [#list type.javaDoc[tag] as tagValue]
          <tag name="${tag}"><![CDATA[${tagValue}]]></tag>
          [/#list]
        [/#list]
        [#if type.annotations["java.lang.Deprecated"]??]
          <tag name="deprecated"/>
        [/#if]
          <facets>
        [#list type.facets as facet]
            <facet>
              <name>${facet.name}</name>
              <value>${facet.value}</value>
              <documentation><![CDATA[${facet.documentation!""}]]></documentation>
            </facet>
        [/#list]
          </facets>
        [#if type.attributes?size > 0]
          <attributes>
          [#list type.attributes as attribute]
            [#if !isFacetExcluded(attribute)]
            <attribute name="${attribute.name}" jsonName="${attribute.jsonMemberName}" typeNamespace="${attribute.baseType.namespace!""}" typeName="${attribute.baseType.qname.localPart}"[#if schemaForNamespace(attribute)??] typeSchemaId="${schemaForNamespace(attribute).id}"[/#if]>
              <![CDATA[${attribute.javaDoc.return!attribute.docValue!"(no documentation provided)"}]]>
            </attribute>
            [/#if]
          [/#list]
          </attributes>
        [/#if]
        [#if type.elements?size > 0]
          <elements>
          [#list type.elements as element]
            [#if !isFacetExcluded(element)]
            <element minOccurs="${element.minOccurs}" maxOccurs="${element.maxOccurs}" jsonName="${element.jsonMemberName}">
              [#if element.docValue??]
              <documentation>
                <![CDATA[${element.docValue}]]>
              </documentation>
              [/#if]
              [#list element.javaDoc?keys as tag]
                [#list element.javaDoc[tag] as tagValue]
              <tag name="${tag}"><![CDATA[${tagValue}]]></tag>
                [/#list]
              [/#list]
              [#if element.annotations["java.lang.Deprecated"]??]
              <tag name="deprecated"/>
              [/#if]
              [#list element.choices as choice]
              <choice name="[#if element.wrapped]${element.wrapperName}/[/#if]${choice.name}" namespace="${choice.namespace!""}"[#if !(choice.ref?? || choice.baseType.anonymous)] typeNamespace="${choice.baseType.namespace!""}" typeName="${choice.baseType.qname.localPart}"[/#if][#if choice.ref?? && schemaForNamespace(choice)??] schemaId="${schemaForNamespace(choice).id}"[#elseif schemaForNamespace(choice)??] typeSchemaId="${schemaForNamespace(choice).id}"[/#if]/>
              [/#list]
            </element>
            [/#if]
          [/#list]
          </elements>
        [/#if]
        [#if type.value??]
          <value jsonName="${type.value.jsonMemberName}" typeNamespace="${type.value.baseType.namespace!""}" typeName="${type.value.baseType.qname.localPart}"[#if schemaForNamespace(type.value)??] typeSchemaId="${schemaForNamespace(type.value).id}"[/#if]>
            <![CDATA[${type.value.javaDoc.return!type.value.docValue!"(no documentation provided)"}]]>
          </value>
        [/#if]
        [#if type.enum]
          <values>
          [#assign enumValueMap=type.enumValues/]
          [#list type.enumConstants as constant]
            [#if enumValueMap[constant.simpleName]??]
            <item value="${enumValueMap[constant.simpleName]?string}">
              [#if constant.docValue??]
              <documentation>
                 <![CDATA[${constant.docValue}]]>
              </documentation>
              [/#if]
              [#list constant.javaDoc?keys as tag]
                [#list constant.javaDoc[tag] as tagValue]
              <tag name="${tag}"><![CDATA[${tagValue}]]></tag>
                [/#list]
              [/#list]
              [#if constant.annotations["java.lang.Deprecated"]??]
              <tag name="deprecated"/>
              [/#if]
            </item>
            [/#if]
          [/#list]
          </values>
        [/#if]
        </type>
      [/#if]
    [/#list]
      </types>
      <elements>
    [#list schema.globalElements as element]
      [#if !isFacetExcluded(element)]
        <element name="${element.name}" type="${element.typeDefinition.qualifiedName}"[#if element.typeDefinition??] typeName="${element.typeDefinition.name!""}" typeNamespace="${element.typeDefinition.namespace!""}"[#if schemaForNamespace(element.typeDefinition)??] typeSchemaId="${schemaForNamespace(element.typeDefinition).id}"[/#if][/#if]>
        [#if element.docValue??]
          <documentation>
            <![CDATA[${element.docValue}]]>
          </documentation>
        [/#if]
        [#list element.javaDoc?keys as tag]
          [#list element.javaDoc[tag] as tagValue]
          <tag name="${tag}"><![CDATA[${tagValue}]]></tag>
          [/#list]
        [/#list]
        [#if element.annotations["java.lang.Deprecated"]??]
          <tag name="deprecated"/>
        [/#if]
          <facets>
        [#list element.facets as facet]
            <facet>
              <name>${facet.name}</name>
              <value>${facet.value}</value>
              <documentation><![CDATA[${facet.documentation!""}]]></documentation>
            </facet>
        [/#list]
          </facets>
        [#if includeExampleXml!false]
          <examplexml><![CDATA[${generateExampleXml(element)?trim}]]></examplexml>
        [/#if]
        [#if includeExampleJson!false]
          <examplejson><![CDATA[${generateExampleJson(element)?trim}]]></examplejson>
        [/#if]
        </element>
      [/#if]
    [/#list]
    [#list schema.localElementDeclarations as element]
      [#if !isDefinedGlobally(element)]
        [#assign localTypeQName=element.elementXmlType.qname/]
        <element name="${element.name}"[#if element.elementTypeDeclaration??] type="${element.elementTypeDeclaration.qualifiedName}"[/#if] typeName="${localTypeQName.localPart}" typeNamespace="${localTypeQName.namespaceURI!""}"[#if schemaForNamespace(element)??] typeSchemaId="${schemaForNamespace(element).id}"[/#if]>
          [#if element.docValue??]
          <documentation>
            <![CDATA[${element.docValue}]]>
          </documentation>
          [/#if]
          [#list element.javaDoc?keys as tag]
            [#list element.javaDoc[tag] as tagValue]
          <tag name="${tag}"><![CDATA[${tagValue}]]></tag>
            [/#list]
          [/#list]
          [#if element.annotations["java.lang.Deprecated"]??]
          <tag name="deprecated"/>
          [/#if]
          [#if includeExampleXml!false]
          <examplexml><![CDATA[${generateExampleXml(element)?trim}]]></examplexml>
          [/#if]
          [#if includeExampleJson!false]
          <examplejson><![CDATA[${generateExampleJson(element)?trim}]]></examplejson>
          [/#if]
        </element>
      [/#if]
    [/#list]
      </elements>
      <facets>
    [#list getFacets(schema) as facet]
        <facet>
          <name>${facet.name}</name>
          <value>${facet.value}</value>
          <documentation><![CDATA[${facet.documentation!""}]]></documentation>
        </facet>
    [/#list]
      </facets>
    </schema>
  [/#if]
[/@forEachSchema]
[@forEachJsonSchema]
  [#if schema.types?size > 0]
    <jsonSchema schemaId="${schema.schemaId}">
    [#if schema.documentation??]
      <documentation>${schema.documentation}</documentation>
    [/#if]
    [#list schema.types as type]
      <type name="${type.typeName}">
      [#if type.docValue??]
        <documentation><![CDATA[${type.docValue}]]></documentation>
      [/#if]
        <facets>
      [#list getFacets(type) as facet]
          <facet>
            <name>${facet.name}</name>
            <value>${facet.value}</value>
            <documentation><![CDATA[${facet.documentation!""}]]></documentation>
          </facet>
      [/#list]
        </facets>
      [#if type.jsonProperties?? && type.jsonProperties?size > 0]
      [#list type.jsonProperties as property]
        <property name="${property.propertyName}" 
                  isList="${property.list}"
                  typeName="${jsonTypeNameForQualifiedName(property.typeName)?xml}"
                  [#if jsonSchemaForType(property.targetType)??]
                  typeSchemaId="${jsonSchemaForType(property.targetType).schemaId}"
                  [/#if]
                  [#if property.propertyDescription??]
                  [#assign d = property.propertyDescription]
                  [#escape d as d?html]
                  documentation="${d}"
                  [/#escape]
                  [/#if] />
      [/#list]
      [/#if]
      [#if type.enumValues?? && type.enumValues?size > 0]
        [#list type.enumValues as enumValue]
          <enumValue>
            <value>${enumValue.name}</value>
          [#if enumValue.description??]
            <documentation><![CDATA[${enumValue.description}]]></documentation>
          [/#if]
          </enumValue>
        [/#list]
      [/#if]
      </type>
    [/#list]
      <facets>
    [#list getFacets(schema) as facet]
        <facet>
          <name>${facet.name}</name>
          <value>${facet.value}</value>
          <documentation><![CDATA[${facet.documentation!""}]]></documentation>>
        </facet>
    [/#list]
      </facets>
    </jsonSchema>
  [/#if]
[/@forEachJsonSchema]
  </data>
  <soap>
    <wsdls>
[@forEachWsdl]
      <wsdl namespace="${wsdl.targetNamespace!""}" namespaceId="${wsdl.id}"[#if wsdl.properties.filename??] file="${wsdl.properties.filename}"[/#if]>
  [@forEachEndpointInterface wsdl=wsdl considerFacets="true"]
        <endpointInterface name="${endpointInterface.serviceName}" id="${endpointInterface.qualifiedName}" package="${endpointInterface.package.qualifiedName}"[#if endpointInterface.metaData.soapPath??] path="${endpointInterface.metaData.soapPath}"[/#if]>
    [#if endpointInterface.docValue??]
          <documentation>
            <![CDATA[${endpointInterface.docValue}]]>
          </documentation>
    [/#if]
    [#list endpointInterface.javaDoc?keys as tag]
      [#list endpointInterface.javaDoc[tag] as tagValue]
          <tag name="${tag}"><![CDATA[${tagValue}]]></tag>
      [/#list]
    [/#list]
    [#if endpointInterface.annotations["java.lang.Deprecated"]??]
          <tag name="deprecated"/>
    [/#if]
          <facets>
        [#list endpointInterface.facets as facet]
            <facet>
              <name>${facet.name}</name>
              <value>${facet.value}</value>
              <documentation><![CDATA[${facet.documentation!""}]]></documentation>
            </facet>
        [/#list]
          </facets>
    [#list endpointInterface.webMethods as method]
      [#if !isFacetExcluded(method)]
          <method name="${method.operationName}" oneWay="${method.oneWay?string}">
        [#if method.docValue??]
            <documentation>
              <![CDATA[${method.docValue}]]>
            </documentation>
        [/#if]
        [#list method.javaDoc?keys as tag]
          [#if (("param" != tag) && ("throws" != tag) && ("exception" != tag) && ("return" != tag))]
            [#list method.javaDoc[tag] as tagValue]
            <tag name="${tag}"><![CDATA[${tagValue}]]></tag>
            [/#list]
          [/#if]
        [/#list]
        [#if method.annotations["java.lang.Deprecated"]??]
            <tag name="deprecated"/>
        [/#if]
        [#list method.webParameters as parameter]
            <parameter name="${parameter.simpleName}[#if parameter.simpleName != parameter.baseParamName] (${parameter.baseParamName})[/#if]" input="${parameter.input?string}" output="${parameter.output?string}"[#if parameter.xmlType??] xmlTypeName="${parameter.xmlType.qname.localPart}" xmlTypeNamespace="${parameter.xmlType.qname.namespaceURI}"[#if schemaForNamespace(parameter.xmlType)??] xmlTypeSchemaId="${schemaForNamespace(parameter.xmlType).id}"[/#if][/#if]>
              <![CDATA[${parameter.docValue!"(no documentation provided)"}]]>
            </parameter>
        [/#list]
        [#if ((!method.oneWay) && (!method.returnType.void))]
          [#assign result=method.webResult/]
            <result[#if result.xmlType??] xmlTypeName="${result.xmlType.qname.localPart}" xmlTypeNamespace="${result.xmlType.qname.namespaceURI}"[#if schemaForNamespace(result.xmlType)??] xmlTypeSchemaId="${schemaForNamespace(result.xmlType).id}"[/#if][/#if]>
              <![CDATA[${method.returnType.docValue!"(no documentation provided)"}]]>
            </result>
        [/#if]
        [#list method.thrownTypes as fault]
            <fault name="${fault.declaration.simpleName}">
              <![CDATA[${fault.docValue!"(no documentation provided)"}]]>
            </fault>
        [/#list]
          </method>
      [/#if]
    [/#list]
        </endpointInterface>
  [/@forEachEndpointInterface]
        <facets>
  [#list getFacets(wsdl) as facet]
          <facet>
            <name>${facet.name}</name>
            <value>${facet.value}</value>
            <documentation><![CDATA[${facet.documentation!""}]]></documentation>
          </facet>
  [/#list]
        </facets>
      </wsdl>
[/@forEachWsdl]
    </wsdls>
  </soap>
  <rest baseAddress="${baseDeploymentAddress}"[#if wadlFilename??] wadl="${wadlFilename}"[/#if]>
    <resources>
[@forEachResourceMethodListByPath considerFacets="true"]
  [#assign hasAnyOperations=false/]
  [#list resources as resource]
    [#if resource.httpMethods?size > 0]
      [#if !isFacetExcluded(resource)]
        [#assign hasAnyOperations=true/]
        [#break/]
      [/#if]
    [/#if]
  [/#list]
  [#if hasAnyOperations]
      <resource name="${(resources?first).fullpath}" subcontext="${(resources?first).metaData.defaultSubcontext!"/rest"}">
        <facets>
    [#list getFacets(resources) as facet]
          <facet>
            <name>${facet.name}</name>
            <value>${facet.value}</value>
            <documentation><![CDATA[${facet.documentation!""}]]></documentation>
          </facet>
    [/#list]
        </facets>
    [#list resources as resource]
      [#if resource.label??]
    <label>${resource.label}</label>
      [/#if]        
      [#if resource.httpMethods?size > 0]
        [#if !isFacetExcluded(resource)]
        <operation name="${resource.httpMethods?first}">
            <additionalHeaderLabels>
          [#list resource.additionalHeaderLabels as headerLabel]
              <label>${headerLabel}</label>
          [/#list]
            </additionalHeaderLabels>
          [#if resource.docValue??]
          <documentation>
            <![CDATA[${resource.docValue}]]>
          </documentation>
          [/#if]
          [#if resource.showSampleRequest??]
            <showSampleRequest>${resource.showSampleRequest}</showSampleRequest>
          [/#if]
          [#if resource.showSampleResponse??]
            <showSampleResponse code="${resource.sampleResponseCode}">${resource.sampleResponseCode}</showSampleResponse>
          [/#if]
          [#if resource.customParameterName??]
            <customParameterName>${resource.customParameterName}</customParameterName>
          [/#if]
          [#list resource.javaDoc?keys as tag]
            [#if (("param" != tag) && ("throws" != tag) && ("exception" != tag) && ("return" != tag))]
              [#list resource.javaDoc[tag] as tagValue]
          <tag name="${tag}"><![CDATA[${tagValue}]]></tag>
              [/#list]
            [/#if]
          [/#list]
          [#list resource.parent.javaDoc?keys as tag]
            [#if (("param" != tag) && ("throws" != tag) && ("exception" != tag) && ("return" != tag))]
              [#list resource.parent.javaDoc[tag] as tagValue]
          <tag name="${tag}"><![CDATA[${tagValue}]]></tag>
              [/#list]
            [/#if]
          [/#list]
          [#if resource.annotations["java.lang.Deprecated"]??]
          <tag name="deprecated"/>
          [/#if]
          [#if resource.parent.annotations["java.lang.Deprecated"]??]
          <tag name="deprecated"/>
          [/#if]
          [#if resource.httpMethods?size > 1]
            [#list resource.httpMethods[1..] as alias]
          <alias>${alias}</alias>
            [/#list]
          [/#if]
          [#list uniqueContentTypes(resource) as contentType]
            [#if contentType.produceable && contentType.subcontexts??]
              [#list contentType.subcontexts as subcontext]
          <contentType type="${contentType.type}" consumable="${contentType.consumable?string}" produceable="${contentType.produceable?string}" subcontext="${subcontext}" path="${subcontext}${resources?first.fullpath}"/>
              [/#list]
            [#else]
          <contentType type="${contentType.type}" consumable="${contentType.consumable?string}" produceable="${contentType.produceable?string}"/>
            [/#if]
          [/#list]
          [#list resource.resourceParameters as parameter]
          <parameter name="${parameter.parameterName}" type="${parameter.typeName!"custom"}"[#if parameter.defaultValue??] defaultValue="${parameter.defaultValue}"[/#if][#if parameter.xmlType??] xmlTypeName="${parameter.xmlType.qname.localPart}" xmlTypeNamespace="${parameter.xmlType.qname.namespaceURI}"[/#if]>
            <![CDATA[${parameter.docValue!"(no documentation provided)"}]]>
          </parameter>
          [/#list]
          [#if resource.entityParameter??]
          <inValue>
            [#if schemaForNamespace(resource.entityParameter)??]<xmlElement elementSchemaId="${schemaForNamespace(resource.entityParameter).id}" elementNamespace="${resource.entityParameter.xmlElement.namespace!""}" elementName="${resource.entityParameter.xmlElement.name}" />[/#if]
            [#if jsonSchemaForType(resource.entityParameter)??]<jsonElementRef elementName="${resource.entityParameter.jsonType.typeName}" elementSchemaId="${jsonSchemaForType(resource.entityParameter).schemaId}"/>[/#if]
            <documentation><![CDATA[${resource.entityParameter.docValue!"(no documentation provided)"}]]></documentation>
          </inValue>
          [/#if]
          [#if resource.representationMetadata??]
          <outValue>
            [#if schemaForNamespace(resource.representationMetadata)??]<xmlElement elementSchemaId="${schemaForNamespace(resource.representationMetadata).id}" elementNamespace="${resource.representationMetadata.xmlElement.namespace!""}" elementName="${resource.representationMetadata.xmlElement.name}" />[/#if]
            [#if jsonSchemaForType(resource.representationMetadata)??]<jsonElementRef elementName="${resource.representationMetadata.jsonType.typeName}" elementSchemaId="${jsonSchemaForType(resource.representationMetadata).schemaId}"/>[/#if]
            <documentation><![CDATA[${resource.representationMetadata.docValue!"(no documentation provided)"}]]></documentation>
          </outValue>
          [/#if]
          [#list resource.statusCodes as statusCode]
          <statusCode code="${statusCode.codeString}">
            <condition><![CDATA[${statusCode.condition!""}]]></condition>
            <additionalHeaders>
            [#list resource.additionalHeaderLabels as headerLabel]
                <additionalHeader>                
              [#list statusCode.additionalHeaders?keys as key]
                [#if headerLabel == key]
                  <![CDATA[${statusCode.additionalHeaders[key]!""}]]>                
                [/#if]
              [/#list]
                </additionalHeader>
            [/#list]
            </additionalHeaders>
          </statusCode>
          [/#list]
          [#list resource.warnings as warning]
          <warning code="${warning.codeString}">
            <![CDATA[${warning.condition!""}]]>
          </warning>
          [/#list]
          [#list resource.responseHeaders?keys as responseHeader]
          <responseHeader>
            <name>${responseHeader}</name>
            <documentation><![CDATA[${(resource.responseHeaders[responseHeader])!""}]]></documentation>
          </responseHeader>
          [/#list]
        </operation>
        [/#if]
      [/#if]
    [/#list]
      </resource>
  [/#if]
[/@forEachResourceMethodListByPath]
    </resources>
    <facets>
  [#list getFacets("rest") as facet]
      <facet>
        <name>${facet.name}</name>
        <value>${facet.value}</value>
        <documentation><![CDATA[${facet.documentation!""}]]></documentation>
      </facet>
  [/#list]
    </facets>
  </rest>
  <packages>
[@forAllPackages var="package"]
    <package id="${package.qualifiedName}">
  [#if package.docValue??]
      <documentation>
        <![CDATA[${package.docValue}]]>
      </documentation>
  [/#if]
  [#list package.javaDoc?keys as tag]
    [#list package.javaDoc[tag] as tagValue]
      <tag name="${tag}"><![CDATA[${tagValue}]]></tag>
    [/#list]
  [/#list]
  [#if package.annotations["java.lang.Deprecated"]??]
      <tag name="deprecated"/>
  [/#if]
    </package>
[/@forAllPackages]
  </packages>
</api-docs>
[/@file]