Documentation des API personnalisées

De RAD Studio
Aller à : navigation, rechercher

Remonter à Extension du moteur RAD Server


RAD Studio vous permet de créer une documentation API pour de nouveaux modules Ressource EMS aux formats YAML et JSON. La nouvelle implémentation est basée sur la spécification de documentation API Swagger RESTful (EN).

EMS.ResourceType implémente les nouveaux attributs pouvant être utilisés pour générer la documentation API des points de terminaison d'une ressource.

EndPointRequestSummary

Description d'une méthode : 

[EndPointRequestSummary('ATags', 'ASummary', 'ADescription', 'AProduces', 'AConsume')]
  • Tags : définit une balise.
  • Summary : titre d'une méthode.
  • Description : description d'une méthode.
  • Produces : type MIME que l'API peut produire. Global pour toutes les API, mais peut être redéfini sur des appels d'API spécifiques. La valeur doit être décrite sous Mime Types.
  • Consume : type MIME que l'API peut consommer. Global pour toutes les API, mais peut être redéfini sur des appels d'API spécifiques. La valeur doit être décrite sous Mime Types.

Exemple de déclaration de la description de la méthode GET d'un point de terminaison : 

[EndPointRequestSummary('Api Doc', 'Get API EndPoints', 'Used to retrieve all the API EndPoints', 'application/json', '')]
procedure Get(const AContext: TEndpointContext; const ARequest: TEndpointRequest; const AResponse: TEndpointResponse);

EndPointRequestParameter

Description des paramètres utilisés dans une requête.

Un paramètre unique est défini par la combinaison d'un nom et d'un emplacement.

Il existe cinq types de paramètres possibles : Path, Query, Header, Body et Form. 

[EndPointRequestParameter('AIn', 'AName', 'ADescription', 'ARequired', 'AType', 'AFormat', 'AItemType', 'AJSONSchema', 'AReference')]
  • ParamIn : l'emplacement du paramètre : Path, Query, Header, Body ou Form.
  • Name : le nom du paramètre. Les noms de paramètres sont sensibles à la casse.
    • Quand l'emplacement du paramètre est 'Body', son nom doit être 'body'.
    • Quand l'emplacement du paramètre est 'Path', son nom doit correspondre au segment de chemin d'accès associé depuis le champ chemin dans l'objet Paths.
    • Dans les autres cas, son nom correspond à ParamIn.
  • Description : brève description du paramètre. Elle peut contenir des exemples d'utilisation. Vous pouvez utiliser la syntaxe GFM pour une représentation de texte formaté.
  • Required : détermine si le paramètre est obligatoire. Si le paramètre est dans 'Path', cette propriété est requise et sa valeur doit être True, sinon la propriété peut être incluse et sa valeur par défaut est False.
  • ParamType : le type du paramètre. Pour des valeurs autres que 'Body', la valeur doit être l'une des valeurs suivantes : 'spArray', 'spBoolean', 'spInteger', 'spNumber', 'spNull', 'spObject', 'spString', 'spFile'. Si ParamType vaut 'spFile', le type MIME consommé doit être soit "multipart/form-data", soit "application/x-www-form-urlencoded" et le paramètre doit être de "form-data". Pour la valeur 'Body', JSONSchema et Reference sont requis.
  • ItemFormat : le format d'extension pour le ParamType : 'None', 'Int32', 'Int64', 'Float', 'Double', 'Byte', 'Date', 'DateTime', 'Password'.
  • ItemType : requis si ParamType a la valeur 'array'. Décrit le type des éléments dans le tableau.
  • JSONSchema : la définition de schéma de la primitive envoyée au serveur. Il s'agit d'une définition de la structure de la requête du corps. Si ParamType vaut 'Array' ou 'Object', un schéma peut être défini.
    • Par exemple :
      Au format JSON : {"type": "object","additionalProperties": {"type": "string"}}.
      Au format YAML :
      type: object
      additionalProperties:
      type: string
  • Reference : La définition de schéma de la primitive envoyée au serveur. Il s'agit d'une définition de la structure de la requête du corps. Si Type vaut 'Array' ou 'Object', un schéma peut être défini.
    • Par exemple :
      '#/definitions/pet'
[EndPointRequestParameter(TAPIDocParameter.TParameterIn.Path, 'item', 'Path Parameter item Description', true, TAPIDoc.TPrimitiveType.spString, TAPIDoc.TPrimitiveFormat.None, TAPIDoc.TPrimitiveType.spString, '', '')]

EndPointResponseDetails

Description des réponses à la requête : 

[EndPointResponseDetails('ACode', 'ADescription', 'AType', 'AFormat', 'ASchema', 'AReference')]
  • Code : le code de réponse.
  • Description : description du code de réponse.
  • PrimitiveType : le type de la primitive (EN) renvoyée. Les types de données primitifs compris dans la spécification Swagger sont basés sur les types pris en charge par le JSON-Schema Draft 4. JSON Schema définit sept types primitifs pour des valeurs JSON : 'spArray', 'spBoolean', 'spInteger', 'spNumber', 'spNull', 'spObject', 'spString'. Voir JSON Schema primitive types (EN). Un type de données primitif supplémentaire, 'spFile', est utilisé par les objets Parameter et Response afin de définir le type de paramètre ou la réponse comme étant un fichier.
  • PrimitiveFormat : le format de la primitive renvoyée, par exemple : 'None', 'Int32', 'Int64', 'Float', 'Double', 'Byte', 'Date', 'DateTime', 'Password'.
  • Schema :
    • Par exemple :
      Au format JSON : {"type": "object","additionalProperties": {"type": "string"}}.
      Au format YAML :
      type: object
      additionalProperties:
      type: string
  • Reference : la définition de schéma de la primitive renvoyée. Il s'agit d'une définition de la structure de la réponse. Si PrimitiveType vaut 'spArray' ou 'spObject', une définition de schéma peut être définie.
    • Par exemple :
      '#/definitions/pet'
[EndPointResponseDetails(200, 'Ok', TAPIDoc.TPrimitiveType.spObject, TAPIDoc.TPrimitiveFormat.None, '', '#/definitions/EmployeeTable')]
[EndPointResponseDetails(404, 'Not Found', TAPIDoc.TPrimitiveType.spNull, TAPIDoc.TPrimitiveFormat.None, '', '')]

EndPointObjectsYAMLDefinitions

Définition des objets pour la version YAML de l'API. 

  [EndPointObjectsYAMLDefinitions(Objects)]
  • Objects : définitions d'objets YAML.
type
  [ResourceName('SampleAttributes')]
  [EndPointObjectsYAMLDefinitions(cYamlDefinitions)]

// YAML Object definition:
  cYamlDefinitions =
  '# ' +  sLineBreak +
  ' PutObject:' +  sLineBreak +
  '   properties:' +  sLineBreak +
  '    EMP_NO:' +  sLineBreak +
  '     type: integer' +  sLineBreak +
  '    FIRST_NAME:' +  sLineBreak +
  '     type: string' +  sLineBreak +
  '    LAST_NAME:' +  sLineBreak +
  '     type: string' +  sLineBreak +
  '    PHONE_EXT:' +  sLineBreak +
  '     type: string' +  sLineBreak +
  '    HIRE_DATE:' +  sLineBreak +
  '     type: string' +  sLineBreak +
  '     format: date-time' +  sLineBreak +
  '    DEPT_NO:' +  sLineBreak +
  '     type: string' +  sLineBreak +
  '    JOB_CODE:' +  sLineBreak +
  '     type: string' +  sLineBreak +
  '    JOB_GRADE:' +  sLineBreak +
  '     type: integer' +  sLineBreak +
  '    JOB_COUNTRY:' +  sLineBreak +
  '     type: string' +  sLineBreak +
  '    SALARY:' +  sLineBreak +
  '     type: integer' +  sLineBreak +
  '    FULL_NAME:' +  sLineBreak +
  '     type: string' +  sLineBreak +
  '# '

EndPointObjectsJSONDefinitions

Définition des objets pour la version JSON de l'API. 

    [EndPointObjectsJSONDefinitions(Objects)]
  • Objects : définitions d'objets JSON.
type
  [ResourceName('SampleAttributes')]
  [EndPointObjectsJSONDefinitions(cJSONDefinitions)]

// JSON Object definition:

cJSONDefinitions =
 '{' +  sLineBreak +
  '   "PutObject": {' +  sLineBreak +
  '       "properties": {' +  sLineBreak +
  '           "EMP_NO": {' +  sLineBreak +
  '               "type": "integer"' +  sLineBreak +
  '           },' +  sLineBreak +
  '           "FIRST_NAME": {' +  sLineBreak +
  '               "type": "string"' +  sLineBreak +
  '           },' +  sLineBreak +
  '           "LAST_NAME": {' +  sLineBreak +
  '               "type": "string"' +  sLineBreak +
  '           },' +  sLineBreak +
  '           "PHONE_EXT": {' +  sLineBreak +
  '               "type": "string"' +  sLineBreak +
  '           },' +  sLineBreak +
  '           "HIRE_DATE": {' +  sLineBreak +
  '               "type": "string",' +  sLineBreak +
  '               "format": "date-time"' +  sLineBreak +
  '           },' +  sLineBreak +
  '           "DEPT_NO": {' +  sLineBreak +
  '               "type": "string"' +  sLineBreak +
  '           },' +  sLineBreak +
  '           "JOB_CODE": {' +  sLineBreak +
  '               "type": "string"' +  sLineBreak +
  '           },' +  sLineBreak +
  '           "JOB_GRADE": {' +  sLineBreak +
  '               "type": "integer"' +  sLineBreak +
  '           },' +  sLineBreak +
  '            "JOB_COUNTRY": {' +  sLineBreak +
  '                "type": "string"' +  sLineBreak +
  '            },' +  sLineBreak +
  '            "SALARY": {' +  sLineBreak +
  '                "type": "integer"' +  sLineBreak +
  '            },' +  sLineBreak +
  '            "FULL_NAME": {' +  sLineBreak +
  '                "type": "string"' +  sLineBreak +
  '            }' +  sLineBreak +
  '        }' +  sLineBreak +
  '    }'

Rubriques

Voir aussi

Récupérée de « http://docwiki.embarcadero.com/RADStudio/Alexandria/f/index.php?title=Documentation_des_API_personnalisées&oldid=212765 »