source upload

contrib/mORMot/CrossPlatform/templates/API.adoc.mustache

@@ -0,0 +1,186 @@
+== API Documentation
+
+NOTE: API Documentation {{exeVersion}} retrieved {{#protocol}}from {{protocol}}://{{host}}/{{uri}} {{/protocol}}at {{time}}.
+
+This documentation has been generated by {{exeInfo}}, running mORMot {{mORMotVersion}}.
+
+WARNING: Any manual modification of this file may be lost after regeneration.
+
+=== Services
+
+This server does publish the following RESTful services:
+
+{{#soa.services}}
+* <<{{uri}}>>.
+{{/soa.services}}
+
+It will also use some <<Objects>>{{#withArrays}}, <<Arrays>>{{/withArrays}}{{#withEnumerates}}, <<Enumerations>>{{/withEnumerates}}{{#withsets}}, <<Sets>>{{/withsets}} type definitions, which will be transmitted as JSON objects, arrays or integers. The expected MIME transmission type, at HTTP level, is `application/json; charset=UTF-8`. Communication protocol may be either `http://` or `https://`, depending on the server configuration.
+
+The following documentation will detail each service, and the input/output JSON content, as expected by each command.
+
+
+{{#soa.services}}
+=== {{uri}}
+
+[.lead]
+{{serviceDescription}}
+
+This `{{uri}}` service does publish the following methods (aka commands):
+
+{{#methods}}
+* <<{{methodName}}>>.
+{{/methods}}
+{{<typeList}}{{#typePascal}}{{#isArray}}* <<{{typePascal}}>>.
+{{/isArray}}
+{{#isRecord}}* <<{{typePascal}}>>.
+{{/isRecord}}
+{{#isEnum}}* <<{{typePascal}}>>.
+{{/isEnum}}{{/typePascal}}{{/typeList}}
+
+{{#methods}}
+==== {{methodName}}
+
+[.lead]
+{{methodDescription}}
+
+.URI (alternatives)
+ POST {{protocol}}://servername:port/{{root}}/{{uri}}.{{methodName}}
+ POST {{protocol}}://servername:port/{{root}}/{{uri}}/{{methodName}}
+
+.Input Body
+----
+{{#hasInParams}}
+{
+{{#args}}
+{{#dirInput}}
+  {{jsonQuote argName}}: {{typePascal}}{{commaInSingle}}
+{{/dirInput}}
+{{/args}}
+}
+{{/hasInParams}}
+{{^hasInParams}}
+No input expected.
+{{/hasInParams}}
+----
+
+.Output Body
+----
+{{#hasOutParams}}
+{
+{{#args}}
+{{#dirOutput}}
+  {{jsonQuote argName}}: {{typePascal}}{{#commaOutResult}},{{/commaOutResult}}
+{{/dirOutput}}
+{{/args}}
+}
+{{/hasOutParams}}
+{{^hasOutParams}}
+No output expected.
+{{/hasOutParams}}
+----
+
+See also:
+
+{{#args}}
+{{>typeList}}
+{{/args}}
+* Other <<{{uri}}>> Services.
+
+{{/methods}}
+
+{{/soa.services}}
+
+{{#withRecords}}
+=== Objects
+
+The following objects are used during data transmission:
+{{<writerec}}{
+{{#fields}}
+{{nestedIdentation}}    {{jsonQuote propName}}: {{typePascal}}{{#nestedRecord}}{{>writerec}}{{nestedIdentation}}    }{{/nestedRecord}}{{#nestedSimpleArray}}array of {{typePascal}}{{/nestedSimpleArray}}{{#nestedRecordArray}}array of {{>writerec}}{{nestedIdentation}}    }{{/nestedRecordArray}}{{^-last}},{{/-last}}
+{{/fields}}{{/writerec}}
+
+{{#records}}
+==== {{name}}
+
+[.lead]
+{{recordDescription}}
+
+.Definition
+----
+{{>writerec}}
+}
+----
+See also:
+
+{{#fields}}
+{{>typeList}}
+{{/fields}}
+* Other <<Objects>>.
+{{#withArrays}}
+* Other <<Arrays>>.
+{{/withArrays}}
+{{#withEnumerates}}
+* Other <<Enumerations>>.
+{{/withEnumerates}}
+{{#withsets}}
+* Other <<Sets>>.
+{{/withsets}}
+
+{{/records}}
+
+{{/withRecords}}
+{{#withArrays}}
+=== Arrays
+
+The following arrays are used during data transmission:
+
+{{#arrays}}
+==== {{name}}
+
+This is a JSON array of <<{{typeSource}}>>.
+
+{{/arrays}}
+
+{{/withArrays}}
+{{#withEnumerates}}
+
+=== Enumerations
+
+When transmitted within other <<Services>>, <<Objects>> or <<Arrays>> content, enumerations are represented by their `integer` JSON value. Any other value will be ignored.
+
+The following enumerations have been defined:
+
+{{#enumerates}}
+==== {{name}}
+
+[.lead]
+{{enumDescription}}
+
+{{#values}}
+ {{-index0}} = {{EnumTrim .}}
+{{/values}}
+
+{{/enumerates}}
+{{/withEnumerates}}
+
+{{#withsets}}
+
+=== Sets
+
+When transmitted within other <<Services>>, <<Objects>> or <<Arrays>> content, sets are represented by their `integer` JSON value, matching binary bit storage. The `integer` values below may be added, to compute the set of individual flags - a value of `0` meaning a void set.
+
+The following sets have been defined:
+
+{{#sets}}
+==== {{name}}
+
+[.lead]
+{{setDescription}}
+
+{{#values}}
+ {{PowerOfTwo -index0}} = {{EnumTrim .}}
+{{/values}}
+
+{{/sets}}
+
+{{/withsets}}