XML v4

gistfile1.xml

<api format="JSON">
	
	<authentication type="header">
		<description><![CDATA[This is a simple header authentication]]><description>
		<parameters>
			<parameter name="X-Pippo-Username" optional="false">
				<description><![CDATA[Please enter here your username]]></description>
			</parameter>
			<parameter name="X-Pippo-Password" optional="false">
				<description><![CDATA[Please enter here your password]]></description>
			</parameter>
		</parameters>
	</authentication>

	<endpoint http="POST" name="Get User" group="Users" authentication="true">
                <description><![CDATA[This is a sample description for the method]]><description>

		<route><![CDATA[/url/{id}]]></route>			
		<parameters>
			<parameter name="id" optional="false" type="String" default="12">
				<!-- Parameter Documentation -->
				<description><![CDATA[This is a sample description for the parameter]]></description>
				<values>
					<value>1</value>
					<value>2</value>
					<value>3</value>
				</values>
			<parameter>
		</parameters>
		
		<!-- The type can be a primitive type (String, Number, Boolean) or a custom Model. -->
		<response type="List[User]" optional="false" />
		
		<!-- Errors -->
		<errors>
			<error code="404">
				<description><![CDATA[The user was not found]]></description>
			</error>
			<error code="500" type="FatalError">
				<description><![CDATA[The user was not found]]></description>
			</error>
		</errors>
		
	</endpoint>
	
	<model name="User">
		<description>This is a User model<description>
		<example>
			<![CDATA[
			{
				“username” : “Marco”
			}
			]]>				
		</example>

		<fields>
			<field name="username" optional="false" type="String" default="pippo">
				<description>This is a sample result field</description>
				<example>3</example>
				<values>
					<value>1</value>
					<value>2</value>
					<value>3</value>
				</values>
			</field>
			<field name="status" optional="false" type="String" >
				<description>This is a sample result field</description>
				<example>active</example>
				<values>
					<value>active</value>
					<value>disabled</value>
					<value>deleted</value>
				</values>
			</field>
		</fields>
	</model>

</api>

La differenza piu grande e' nella definizione degli array, dove ho rubato il modello a Swagger:

List[String] 
List[Number] 
List[Boolean] 
List[Model]

In questo modo evitiamo di aggiungere un nuovo attributo array nei <parameter> e <field>, e inoltre diamo consistenza alla vecchia sintassi che a volte aveva l'attributo object a volte l'attributo type.

L'attributo default, come tu Mik suggerivi, non e' nella documentation ma nella definizione dell'oggetto, perche' appunto ha un ruolo piu' attivo (nel senso che viene prevalorizzato nelle clients).

Implementandolo ho fatto un paio di modifiche su cui discutere:

Ho rinominato l'elemento response in result, più simile a com'era prima. Da un lato reponse è più orientato al concetto HTTP, però a questo punto andrebbe cambiato method in qualcosa che richiami più l'endpoint

Una cosa meno di facciata: parameter e field fanno riferimento alla stessa struttura XML, per cui hanno gli stessi identici parametri e nodi figli. Pu' essere una limitazione?

<method> potrebbe diventare <operation> oppure <endpoint>, e <result> in <response>.

<parameter> e <field> sono simili e appartengono allo stesso oggetto Field.java (anzi, JsonField.java), ma dal momento che hanno due nomi diversi il giorno in cui noi dovremmo espandere, che ne so, il <parameter>, possiamo farlo nel parser (e magari fargli fare proprio riferimento ad un oggetto Parameter.java, anzi JsonParameter.java) senza intaccare l'oggetto <field>.

Il type nell'error è necessario?

Potremmo aggiungerlo dopo come una enumeration per indicare la gravità dell'errore, sulla quale fare delle statistiche/report, però al momento mi sembra solo un'appesantimento (c'è già la description)

L'error molte volte ha una risposta (quasi sempre). Per noi la gestione del Model nell'error e' indifferente, e' come se fosse il model di un field qualsiasi. Io direi di aggiungerlo, ad esempio oggi i developer di Marco Trombetti mi avevano chiesto se potevano farlo e gli ho detto di si.