Benutzerdefinierte API-Dokumentation

Aus RAD Studio
Wechseln zu: Navigation, Suche

Nach oben zu Erweitern der RAD Server Engine


In RAD Studio können Sie API-Dokumentationen für neue RAD Server-Ressourcenmodule im YAML- und JSON-Format erstellen. Die neue Implementierung basiert auf der Swagger RESTful API Documentation Specification (EN).

EMS.ResourceType implementiert die neuen Attribute, mit denen die API-Dokumentation für die Endpunkte einer Ressource erzeugt werden kann.

EndPointRequestSummary

Beschreibung einer Methode 

[EndPointRequestSummary('ATags', 'ASummary', 'ADescription', 'AProduces', 'AConsume')]
  • Tags: Definiert einen Tag.
  • Summary: Ein Methodentitel.
  • Description: Eine Methodenbeschreibung.
  • Produces: Ein MIME-Typ, den die API erzeugen kann. Dies gilt generell für alle APIs, kann jedoch für bestimmte API-Aufrufe überschrieben werden. Der Wert muss der Beschreibung unter Mime-Typen entsprechen.
  • Consume: Ein MIME-Typ, den eine API verwenden kann. Dies gilt generell für alle APIs, kann jedoch für bestimmte API-Aufrufe überschrieben werden. Der Wert muss der Beschreibung unter Mime-Typen entsprechen.

Beispiel einer Beschreibungsdeklaration einer GET-Methode eines Endpunkts: 

[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

Beschreibung der in einer Anforderung verwendeten Parameter.

Ein eindeutiger Parameter wird durch eine Kombination eines Namens und einer Position definiert.

Es gibt fünf mögliche Parametertypen: Path, Query, Header, Body und Form. 

[EndPointRequestParameter('AIn', 'AName', 'ADescription', 'ARequired', 'AType', 'AFormat', 'AItemType', 'AJSONSchema', 'AReference')]
  • ParamIn: Die Position des Parameters: Path, Query, Header, Body oder Form.
  • Name: Der Name des Parameters. Bei Parameternamen wird zwischen Groß- und Kleinschreibung unterschieden.
    • Wenn die Position des Parameters "Body" ist, muss der Name "body" lauten.
    • Wenn die Position des Parameters "Path" ist, muss der Name mit dem zugeordneten Pfadsegment aus dem Pfadfeld im Pfadobjekt übereinstimmen.
    • Für die restlichen Fälle entspricht der Name ParamIn.
  • Description: Eine kurze Beschreibung des Parameters. Diese kann Verwendungsbeispiele enthalten. GFM-Syntax kann zur Darstellung von Rich-Text verwendet werden.
  • Required: Legt fest, ob dieser Parameter obligatorisch ist. Wenn sich dieser Parameter in "Path" befindet, wird diese Eigenschaft benötigt, und der Wert muss True sein, andernfalls kann die Eigenschaft mit dem Wert False enthalten sein.
  • ParamType: Der Typ des Parameters. Für einen anderen Wert als "Body" muss einer der folgenden Werte verwendet werden: 'spArray', 'spBoolean', 'spInteger', 'spNumber', 'spNull', 'spObject', 'spString', 'spFile'. Wenn ParamType 'spFile' ist, muss der verwendete MIME-Typ entweder "multipart/form-data" oder "application/x-www-form-urlencoded" sein, und der Parameter muss sich in "form-data" befinden. Für den Wert "Body" werden JSONSchema und Reference benötigt.
  • ItemFormat: Das erweiternde Format für ParamType: 'None', 'Int32', 'Int64', 'Float', 'Double', 'Byte', 'Date', 'DateTime', 'Password'.
  • ItemType: Ist erforderlich, wenn ParamType 'array' ist. Dieser Typ beschreibt den Typ der Elemente im Array.
  • JSONSchema: Die Schemadefinition des primitiven Typs, der an den Server gesendet wurde. Eine Definition der Rumpf-Anforderungsstruktur. Wenn ParamType "Array" oder "Object" ist, kann ein Schema definiert werden.
    • Zum Beispiel:

Im JSON-Format: {"type": "object","additionalProperties": {"type": "string"}}.

    • Im YAML-Format:
      type: object
      additionalProperties:
      type: string

Reference: Die Schema-Definition des primitiven Typs, der an den Server gesendet wurde. Eine Definition der Rumpf-Anforderungsstruktur. Wenn "Type" "Array" oder "Object" ist, kann ein Schema definiert werden.

    • Zum Beispiel:
      '#/definitions/pet'
[EndPointRequestParameter(TAPIDocParameter.TParameterIn.Path, 'item', 'Path Parameter item Description', true, TAPIDoc.TPrimitiveType.spString, TAPIDoc.TPrimitiveFormat.None, TAPIDoc.TPrimitiveType.spString, '', '')]

EndPointResponseDetails

Beschreibung der Anforderungsantworten: 

[EndPointResponseDetails('ACode', 'ADescription', 'AType', 'AFormat', 'ASchema', 'AReference')]
  • Code: Der Antwortcode.
  • Description: Beschreibung des Antwortcodes.
  • PrimitiveType: Der Typ des zurückgegebenen primitiven Typs (EN). Primitive Datentypen in der Swagger-Spezifikationen basieren auf den Typen, die vom JSON-Schema Draft 4 unterstützt werden. Das JSON-Schema definiert sieben primitive Typen für JSON-Werte: 'spArray', 'spBoolean', 'spInteger', 'spNumber', 'spNull', 'spObject', 'spString'. Siehe JSON Schema primitive types (EN). Ein zusätzlicher primitiver Datentyp, 'spFile', wird vom Parameter-Objekt und dem Antwort-Objekt verwendet, um den Parametertyp oder die Antwort als Datei festzulegen.
  • PrimitiveFormat: Das Format des zurückgegebenen primitiven Typs, zum Beispiel: 'None', 'Int32', 'Int64', 'Float', 'Double', 'Byte', 'Date', 'DateTime', 'Password'.
  • Schema:
    • Zum Beispiel:

Im JSON-Format: {"type": "object","additionalProperties": {"type": "string"}}.

    • im YAML-Format:
      type: object
      additionalProperties:
      type: string
  • Reference: Die Schemadefinition des zurückgegebenen primitiven Typs. Eine Definition der Antwortstruktur. Wenn PrimitiveType "spArray" oder "spObject" ist, kann ein Schema definiert werden:
    • Zum Beispiel:
      '#/definitions/pet'
[EndPointResponseDetails(200, 'Ok', TAPIDoc.TPrimitiveType.spObject, TAPIDoc.TPrimitiveFormat.None, '', '#/definitions/EmployeeTable')]
[EndPointResponseDetails(404, 'Not Found', TAPIDoc.TPrimitiveType.spNull, TAPIDoc.TPrimitiveFormat.None, '', '')]

EndPointObjectsYAMLDefinitions

Definition von Objekten für die API-YAML-Version. 

  [EndPointObjectsYAMLDefinitions(Objects)]
  • Objects: YAML-Objekte-Definitionen.
type
  [ResourceName('SampleAttributes')]
  [EndPointObjectsYAMLDefinitions(cYamlDefinitions)] 

// YAML Object definition: 
   cYamlDefinitions = '''
   #
    PutObject:
      properties:
       EMP_NO:
        type: integer
       FIRST_NAME:
        type: string
       LAST_NAME:
        type: string
       PHONE_EXT:
        type: string
       HIRE_DATE:
        type: string
        format: date-time
       DEPT_NO:
        type: string
       JOB_CODE:
        type: string
       JOB_GRADE:
        type: integer
       JOB_COUNTRY:
        type: string
       SALARY:
        type: integer
       FULL_NAME:
        type: string
   # 
   ...
Hinweis: Wenn die YAML-Definition fehlt und nur die JSON-Definition vorhanden ist, wird die JSON-Definition automatisch in das YAML-Format konvertiert.

EndPointObjectsJSONDefinitions

Definition von Objekten für die API-JSON-Version. 

    [EndPointObjectsJSONDefinitions(Objects)]
  • Objects: JSON-Objekte-Definitionen.
type
  [ResourceName('SampleAttributes')]
  [EndPointObjectsJSONDefinitions(cJSONDefinitions)]

// JSON Object definition:

cJSONDefinitions = '''
  {
     "PutObject": {
         "properties": {
             "EMP_NO": {
                 "type": "integer"
             },
             "FIRST_NAME": {
                 "type": "string"
             },
             "LAST_NAME": {
                 "type": "string"
             },
             "PHONE_EXT": {
                 "type": "string"
             },
             "HIRE_DATE": {
                 "type": "string",
                 "format": "date-time"
             },
             "DEPT_NO": {
                 "type": "string"
             },
             "JOB_CODE": {
                 "type": "string"
             },
             "JOB_GRADE": {
                 "type": "integer"
             },
              "JOB_COUNTRY": {
                  "type": "string"
              },
              "SALARY": {
                  "type": "integer"
              },
              "FULL_NAME": {
                  "type": "string"
              }
          }
      }
  '''
Hinweis: Wenn die JSON-Definition fehlt und nur die YAML-Definition vorhanden ist, wird die YAML-Definition automatisch in das JSON-Format konvertiert.

Themen

Siehe auch

Abgerufen von „https://docwiki.embarcadero.com/RADStudio/Florence/d/index.php?title=Benutzerdefinierte_API-Dokumentation&oldid=221771“