3.10 WSDL-kirjelduse dokumenteerimine

X-tee kontekstis olulise informatsiooni edasiandmiseks võib WSDL-kirjeldusele lisada X-tee spetsiifilised dokumentatsioonielemendid, mis võimaldavad andmeteenuseid (WSDL operatsioone) annoteerida andmeteenuse versiooni, pealkirja ja kasutajale ja arendajale mõeldud kommentaaridega.

Kui dokumentatsioonielemente on WSDL-kirjelduse sees korrektselt kasutatud, saab WSDL-kirjelduse põhjal luua MISP2 portaali kasutajaliidese (https://github.com/jointxroad/components/blob/master/component_descriptions.md#x-road-portal-misp2), mida on mugav kasutada andmeteenuse testimiseks ja vajadusel ka selleks, et luua odav veebiliides lõppkasutaja jaoks.

Dokumentatsioonielemendid on kirjeldatud järgmises tabelis 3.

Tabel 3   X-tee dokumentatsioonielemendid

Dokumentatsioonielement

Kirjeldus

/definitions/binding/operation/@name

Andmeteenuse kood

/definitions/binding/operation/xrd:version

Andmeteenuse versioon

/definitions/portType/operation/documentation/xrd:title

Andmeteenuse pealkiri (kasutajale näitamiseks)

/definitions/portType/operation/documentation/xrd:notes

Andmeteenuse kommentaar (kasutajale näitamiseks)

/definitions/portType/operation/documentation/xrd:techNotes

Andmeteenuse kommentaar (arendajale)

 

X-tee spetsiifilised dokumentatsioonielemendid on mõeldud eelkõige lõppkasutaja jaoks. Nende alusel peab olema võimalik automaatselt genereerida andmeteenustele veebiliideseid. Dokumentatsioonielemendid on väga vajalikud ka arendajatele, kes liidestavad infosüsteeme ning ka äriinimestele, kes loevad neid kirjeldusi RIHA-s.

Andmeteenuste annoteerimine saab toimuda järgmistel tasemetel:

  • 0-tase: WSDL ei sisalda ühtegi inimkasutajale mõeldud märgendit ja on mõeldud ainult süsteemseks kasutamiseks;
  • 1-tase: WSDL annoteeritakse ja andmeteenus toetab mõningast kasutamist näiteks MISP2 portaali vahendusel;
  • 2-tase: Andmeteenuse (või andmeteenuste) mugavaks kasutamiseks XForms tehnoloogiat toetavas keskkonnas luuakse eraldiseisev XForms kirjeldus, millele viidatakse andmeteenuse (või andmeteenuste) dokumentatsioonis.

XForms standardist räägitakse põhjalikumalt moodulis 7 (pt 7.2).


Arendajale mõeldud märkused saab panna XML-kommentaari sisse. Nii saab anda WSDL dokumendi sees ülevaate andmeteenuse tööst või selgitada paremini andmeteenuse struktuuri.

Elementide nimetused peavad olema võimalikult lihtsad ja arusaadavad ning elementide ja andmeteenuste nimetused peavad andma hea ülevaate nende tähendusest.


Last modified: Tuesday, 16 May 2017, 12:19 PM