enunciate template for asciidoc

gistfile1.txt

[#ftl]
[#--

    Copyright © 2006-2016 Web Cohesion (info@webcohesion.com)

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

--]
[#-- @ftlvariable name="resourceApis" type="java.util.List<com.webcohesion.enunciate.api.resources.ResourceApi>" --]
[#-- @ftlvariable name="serviceApis" type="java.util.List<com.webcohesion.enunciate.api.services.ServiceApi>" --]
[#-- @ftlvariable name="data" type="java.util.List<com.webcohesion.enunciate.api.datatype.Syntax>" --]
[#-- @ftlvariable name="downloads" type="java.util.List<com.webcohesion.enunciate.api.Download>" --]
[#-- @ftlvariable name="title" type="java.lang.String" --]
[#-- @ftlvariable name="indexPageName" type="java.lang.String" --]
[#-- @ftlvariable name="disableMountpoint" type="java.lang.Boolean" --]
[#-- @ftlvariable name="disableResourceLinks" type="java.lang.Boolean" --]
[#-- @ftlvariable name="apiRelativePath" type="java.lang.String" --]
[#-- @ftlvariable name="cssFile" type="java.lang.String" --]
[#-- @ftlvariable name="additionalCssFiles" type="java.util.List<java.lang.String>" --]
[#-- @ftlvariable name="copyright" type="java.lang.String" --]
[#-- @ftlvariable name="apiDoc" type="java.lang.String" --]
[#-- @ftlvariable name="swaggerUI" type="com.webcohesion.enunciate.api.InterfaceDescriptionFile" --]
[#-- @ftlvariable name="favicon" type="java.lang.String" --]
[#-- @ftlvariable name="includeApplicationPath" type="java.lang.Boolean" --]
[#--
     Macro to transform html tags from javadoc to asciidoc syntax
     Some styles may not be available in an asciidoc table
     /!\ may need improvements
--]
[#macro html2asciidoc t table=false]
[#if table==true]
${t?replace("<li>", "")?replace("</li>", "\n")?replace("<p>", "\n")?replace("</p>", "\n")?replace("<b>","*")?replace("</b>", "*")?replace("<i>", "_")?replace("</i>", "_")?replace("<ul>", "\n")?replace("</ul>", "\n")?replace("|", "\\|")?replace("<pre.*?>", "`", "r")?replace("</pre>", "`")?replace("<h\\d>", "\n*", "r")?replace("</h\\d>", "*\n", "r")?replace("<br>", "")?replace("&lt;", "<")?replace("&gt;", ">")}
[#else]
${t?replace("<li>", "* ")?replace("</li>", "\n")?replace("<p>", "\n")?replace("</p>", "\n")?replace("<b>","*")?replace("</b>", "*")?replace("<i>", "_")?replace("</i>", "_")?replace("<ul>", "\n")?replace("</ul>", "\n")?replace("<pre.*?>", "\n---\n", "r")?replace("</pre>", "\n---\n")?replace("<h\\d>", "\n*", "r")?replace("</h\\d>", "*\n", "r")?replace("<br>", "\n")?replace("&lt;", "<")?replace("&gt;", ">")}
[/#if]
[/#macro]
[#--
     Processing asciidoc file
--]
[@file name="documentation_en.adoc"]
= ${title}
:toc:
:icons:
:numbered:

== Introduction
This document describes the operations, services and data types for ${title}.

[#if serviceApis?size > 0]
[#list serviceApis as serviceApi]
[#list serviceApi.serviceGroups as serviceGroup]
[#list serviceGroup.services as service]
== Operations [#if service.label??]${service.label!""}[/#if]

=== Introduction
[#if service.description??]
[@html2asciidoc t=service.description!"" /]

[/#if]
[#if service.namespace?? && service.namespace?length > 0]
*Namespace* : ${service.namespace}
[/#if]
[#if service.path??]
*Path* : ${service.path}
[/#if]
[#if service.since??]
*Available Since* : ${service.since}
[/#if]
[#if service.version??]
*Version* : ${service.version}
[/#if]
[#if service.deprecated??]
[WARNING]
This service has been deprecated.
[/#if]
[#list service.operations as operation]

=== ${operation.name}
[#if (operation.since?? || operation.version??)]
|===========================================
[#if method.since??]
|Available Since       |${operation.since}
[/#if]
[#if method.version??]
|Version               |${operation.version}
[/#if]
|===========================================
[/#if]
[#if operation.deprecated??]
[WARNING]
This method has been deprecated.

[/#if]
[#if operation.description??]
[@html2asciidoc t=operation.description!"" /]
[/#if]

[#if operation.inputParameters?size > 0]
.Input Parameters
[options="header"]
|==========================================
^|Name ^|Type ^| Description
[#list operation.inputParameters as parameter]
|${parameter.name}|${parameter.dataType.label!"_(custom)_"}|[@html2asciidoc t=parameter.description!"" table=true /]
[/#list]
|==========================================
[/#if]

[#if operation.outputParameters?size > 0]
.Output Parameters
[options="header"]
|==========================================
^|Name ^|Type ^| Description
[#list operation.outputParameters as parameter]
|${parameter.name}|${parameter.dataType.label!"_(custom)_"}|[@html2asciidoc t=parameter.description!"" table=true/]
[/#list]
|==========================================
[/#if]

[#if operation.returnType??]
.Return Value
[options="header"]
|==========================================
^|Type ^| Description
|${operation.returnType.label!"_(custom)_"}|${operation.returnDescription!""}
|==========================================
[/#if]

[#if operation.faults?size > 0]
.Faults
[options="header"]
|==========================================
^|Name ^|Type ^|Conditions
[#list operation.faults as fault]
|${fault.name}|${fault.dataType.label!"_(custom)_"}|${fault.conditions!""}
[/#list]
|==========================================
[/#if]
[/#list]
[/#list]
[/#list]
[/#list]
[/#if]

[#list resourceApis as resourceApi]
[#list resourceApi.resourceGroups as resourceGroup]
== Resources ${resourceGroup.label!""}
=== Introduction
[#if resourceGroup.description??]
[@html2asciidoc t=resourceGroup.description!"" /]
[/#if]
[#if resourceGroup.deprecated??]
[WARNING]
This set of resources has been deprecated.

[/#if]
[#list resourceGroup.resources as resource]
[#list resource.methods as method]
[#-- 
   /!\ keeping last path item as title
--]
=== ${resource.path[1..]?keep_before("/")} (${method.label})
*Path*   : `[#if resourceGroup.relativeContextPath?length > 0]${resourceGroup.relativeContextPath}/[/#if]${resource.path}`

*Method* : ${method.label}

[#if resourceGroup.deprecated?? || method.deprecated??]
[WARNING]
This method has been deprecated.
[/#if]

[#assign securityRoles=method.securityRoles![]/]
[#if (method.since?? || method.version?? || securityRoles?size > 0)]
[grid="rows",format="csv"]
|=============================================================================================
[#if method.since??]
|Available Since       |${method.since}
[/#if]
[#if method.version??]
|Version               |${method.version}
[/#if]
[#if securityRoles?size > 0]
|Security Roles Allowed|[#list securityRoles as role]${role}[#if role_has_next],[/#if][/#list]
[/#if]
|=============================================================================================
[/#if]

[#if method.description??]
[@html2asciidoc t=method.description!"" /]
[/#if]

[#if method.parameters?size > 0]
[#assign includeDefault=method.includeDefaultParameterValues/]
[#assign includeConstraints=method.hasParameterConstraints/]
[#assign includeMultiplicity=method.hasParameterMultiplicity/]
.Request Parameters
[options="header"]
|==========================================
^|Name ^|Type ^|Description [#if includeDefault] ^|Default[/#if] [#if includeConstraints] ^|Constraints[/#if] [#if includeMultiplicity] ^|Multivalued[/#if]
[#list method.parameters as parameter]
|${parameter.name}|${parameter.typeLabel}|[@html2asciidoc t=parameter.description!"" table=true/] [#if includeDefault]|${parameter.defaultValue!""}[/#if] [#if includeConstraints]|${parameter.constraints!""}[/#if] [#if includeMultiplicity]|${parameter.multivalued?string("yes", "no")}[/#if]
[/#list]
|==========================================
[/#if]

[#if method.requestEntity??]
.Request Body
[options="header"]
|==========================================
^|Media type ^|Data type [#if method.requestEntity.description??]^|Description[/#if]
[#list method.requestEntity.mediaTypes as io]
|${io.mediaType}|${io.dataType.label!"_(custom)_"} [#if io.syntax??](${io.syntax})[/#if] [#if io_index = 0 && method.requestEntity.description??][#if method.requestEntity.mediaTypes?size > 1] .${method.requestEntity.mediaTypes?size}+^.^[/#if]|[@html2asciidoc t=method.requestEntity.description!"" table=true /][/#if]
[/#list]
|==========================================
[/#if]

[#if method.responseCodes?size > 0]
[#assign hasExpectedTypes=false/]
[#list method.responseCodes as responseCode]
  [#if responseCode.mediaTypes?size > 0]
    [#assign hasExpectedTypes=true/]
  [/#if]
[/#list]
.Response Codes
[options="header"]
|==========================================
^|Code ^|Condition ^[#if hasExpectedTypes]|Type[/#if]
[#list method.responseCodes as responseCode]
|${responseCode.code}|${responseCode.condition!""} [#if hasExpectedTypes]| 
[#list responseCode.mediaTypes as io]
  [#if io.syntax??]- (${io.syntax})[/#if] 
[/#list]
[/#if]
[/#list]
|==========================================
[/#if]

.Response Body
[options="header"]
|==========================================
^|Media type ^|Data type ^[#if method.responseEntity.description??]|Description[/#if]
[#list method.responseEntity.mediaTypes as io]
|${io.mediaType}|${io.dataType.label!"_(custom)_"} [#if io.syntax??] (${io.syntax})[/#if] [#if io_index = 0 && method.responseEntity.description??][#if method.responseEntity.mediaTypes?size > 1] .${method.responseEntity.mediaTypes?size}+^.^[/#if]|[@html2asciidoc t=method.responseEntity.description!"" table=true/][/#if]
[/#list]
|==========================================

[#if method.warnings?size > 0]
.Response Warnings
|==========================================
^|Code ^|Condition
[#list method.warnings as responseCode]
|${responseCode.code}|${responseCode.condition}
[/#list]
|==========================================
[/#if]

[#if method.responseHeaders?size > 0]
.Response Headers
[options="header"]
|==========================================
^|Name ^|Description
[#list method.responseHeaders as header]
|${header.name}|[@html2asciidoc t=header.description!"" table=true /]
[/#list]
|==========================================
[/#if]

[#if method.example??]
.*Request example*
----
${method.example.requestHeaders}

[#if method.example.requestLang??]${method.example.requestBody}[/#if]
----

.*Response example*
----
${method.example.responseHeaders}

${method.example.responseBody}
----
[/#if]

[/#list]
[/#list]
[/#list]
[/#list]

[#if data?size > 0]
[#list data as syntax]
== ${syntax.label} objects
[#list syntax.namespaces as ns]
[#list ns.types as type]
=== ${type.label}
[#if type.namespace.uri??]
*Namespace* : [#if type.namespace.uri?length > 0]${type.namespace.uri}[#else](Default)[/#if]
[/#if]
[#if type.since??]
*Available Since* : ${type.since}
[/#if]
[#if type.version??]
*Version* : ${type.version}
[/#if]
[#if type.abstract]
*Abstract Type*
[/#if]
[#if type.subtypes??]
*Subtypes* : [#list type.subtypes as subtype]${subtype.label}[#if subtype_has_next], [/#if][/#list]
[/#if]

[#if type.deprecated??]
[WARNING]
This data type has been deprecated.

[/#if]
[#if type.description??]
[@html2asciidoc t=type.description!"" /]
[/#if]

[#if type.values??]
.Values
[options="header"]
|==========================================
^|Value ^|Description
[#list type.values as value]
|${value.value}|[@html2asciidoc t=value.description!"" table=true/]
[/#list]
|==========================================
[/#if]
[#if type.properties??]
.Properties
[options="header"]
[#assign nbcolumns=3 /]
|==========================================
^|Name ^| Data type [#list type.propertyMetadata?keys as meta][#assign nbcolumns+=1 /] ^|${type.propertyMetadata[meta]}[/#list]^|Description
[#list type.properties as property]
|${property.name}|${property.dataType.label!"_(custom)_"}[#list type.propertyMetadata?keys as meta]|[#assign metaValue=property[meta]!({ "structure" : true })/][#if metaValue?is_hash && metaValue.structure!false]${metaValue.value!""}[#else]${metaValue}[/#if][/#list]|[@html2asciidoc t=property.description!"" table=true /]
[/#list]
[#if type.supertypes??]
[#list type.supertypes as supertype]
[#if supertype.value?? && supertype.value.properties?? && supertype.value.properties?size > 0]
${nbcolumns}+|Properties inherited from ${supertype.label}
[#list supertype.value.properties as superProperty]
|${superProperty.name}|${superProperty.dataType.label!"_(custom)_"}[#list type.propertyMetadata?keys as meta]|[#assign metaValue=superProperty[meta]!({ "structure" : true })/][#if metaValue?is_hash && metaValue.structure!false]${metaValue.value!""}[#else]${metaValue}[/#if][/#list]|[@html2asciidoc t=superProperty.description!"" table=true/]
[/#list]
[/#if]
[/#list]
[/#if]
|==========================================
[/#if]
[#if type.example??]
.*Example*
----
${type.example.body}
----
[#if type.abstract]
[WARNING]
This data type is abstract. The example above may be incomplete. More accurate examples can be found in subtypes sections.

[/#if]
[/#if]
[/#list]
[/#list]
[/#list]
[/#if]
[/@file]