1. Einführung
In diesem vierten Artikel unserer Reihe über RAML - der RESTful API Modeling Language - zeigen wir , wie Sie mit annotations benutzerdefinierte Eigenschaften für eine RAML-API-Spezifikation definieren. Dieser Prozess wird auch als Erweiterung der Metadaten der Spezifikation bezeichnet.
Annotationen können verwendet werden, um Hooks für RAML-Verarbeitungswerkzeuge bereitzustellen, die zusätzliche Spezifikationen erfordern, die außerhalb der Amtssprache liegen.
2. Annotationstypen deklarieren
Ein oder mehrere annotation-Typen können mit der annotationTypes-Eigenschaft der obersten Ebene deklariert werden.
In den einfachsten Fällen reicht der Name des Annotationstyps aus, um ihn anzugeben. In diesem Fall wird der Annotationstypwert implizit als Zeichenfolge definiert:
annotationTypes:
simpleImplicitStringValueType:Dies ist das Äquivalent zur hier expliziteren Definition des annotation type :
annotationTypes:
simpleExplicitStringValueType:
type: stringIn anderen Fällen enthält eine annotation type -Spezifikation ein Wertobjekt, das als __annotation type-Deklaration angesehen wird.
In diesen Fällen wird der annotation-Typ unter Verwendung derselben Syntax wie ein data-Typ mit zwei optionalen Attributen definiert:
allowedTargets , dessen Wert entweder eine Zeichenfolge oder ein String-Array ist, das die Arten von Zielpositionen begrenzt, auf die eine annotation angewendet werden kann, und allowMultiple , deren boolescher Wert angibt, ob die annotation innerhalb eines einzelnen Ziels mehrmals angewendet werden darf oder Standard ist false ).
Hier ist ein kurzes Beispiel, in dem ein Annotationstyp__ mit zusätzlichen Eigenschaften und Attributen deklariert wird:
annotationTypes:
complexValueType:
allowMultiple: true
properties:
prop1: integer
prop2: string
prop3: boolean2.1. Zielorte, die die Verwendung von Anmerkungen unterstützen
Annotations kann auf mehrere Zielspeicherorte auf Stammebene angewendet werden (verwendet in), einschließlich der Stammebene der API selbst, resource types , traits , data types , documentation items , security schemata , libraries , overlays , extensions____.
Annotationen können auch auf Sicherheitsschemaeinstellungen , resources , methods , response -Deklarationen, request body , response body und named Beispiele angewendet werden.
2.2. Ziele eines Annotationstyps einschränken
Um einen Annotationstyp auf einen oder mehrere bestimmte Zielorttypen einzuschränken, definieren Sie das Attribut allowedTargets .
Wenn Sie einen annotation-Typ auf einen einzelnen Zielstandorttyp beschränken, weisen Sie dem Attribut allowedTargets einen Zeichenfolgenwert zu, der diesen Zielstandorttyp darstellt:
annotationTypes:
supportsOnlyOneTargetLocationType:
allowedTargets: TypeDeclarationUm mehrere Zielstandorttypen für einen annotation-Typ zuzulassen, weisen Sie dem Attribut allowedTargets ein Array von Zeichenfolgenwerten zu, die diese Zielstandorttypen darstellen:
annotationTypes:
supportsMultipleTargetLocationTypes:
allowedTargets:[Library, Overlay, Extension]----
Wenn das Attribut __allowedTargets__ nicht für einen Annotationstyp__ definiert ist, kann dieser Annotationstyp standardmäßig auf alle unterstützenden Zielorttypen angewendet werden.
[[applying]]
=== ** 3. Annotationstypen anwenden **
Nachdem Sie die __annotation types__ auf der Stammebene Ihrer RAML-API-Spezifikation definiert haben, wenden Sie sie auf die vorgesehenen Zielpositionen an und geben deren Eigenschaftswerte für jede Instanz an. Die Anwendung eines Annotationstyps__ innerhalb eines Zielorts wird einfach als __annotation__ an diesem Zielort bezeichnet.
==== ** 3.1. Syntax**
Um einen Annotationstyp__ anzuwenden, fügen Sie den in Klammern () eingeschlossenen __annotation-Typ name__ als Attribut des Zielorts hinzu und geben Sie die __annotation-Typwerteigenschaften an, die der __annotation-Typ__ für dieses bestimmte Ziel verwenden soll. Wenn sich der __annotation-Typ__ in einer RAML-__library__ befindet, verketten Sie die __library__-Referenz, gefolgt von einem Punkt (.), Gefolgt vom __annotation-Typnamen.
==== ** 3.2. Beispiel**
Ein Beispiel zeigt, wie wir einige der in den obigen Codeausschnitten aufgeführten __annotation-Typen auf verschiedene __resources__ und __methods__ unserer API anwenden können:
[source,javascript,gutter:,true]
----/foos:
type: myResourceTypes.collection
(simpleImplicitStringValueType): alpha
...
get:
(simpleExplicitStringValueType): beta
...
/{fooId}:
type: myResourceTypes.item
(complexValueType):
prop1: 4
prop2: testing
prop3: true4. Anwendungsfall
Ein möglicher Anwendungsfall für annotations wäre das Definieren und Konfigurieren von Testfällen für eine API.
Angenommen, wir wollten ein RAML-Verarbeitungstool entwickeln, das eine Reihe von Tests für unsere API basierend auf annotations generieren kann. Wir könnten den folgenden Annotationstyp definieren:
annotationTypes:
testCase:
allowedTargets:[Method] allowMultiple: true
usage: |
Use this annotation to declare a test case.
You may apply this annotation multiple times per location.
properties:
scenario: string
setupScript?: string[] testScript: string[] expectedOutput?: string
cleanupScript?: string[]----
Wir könnten dann eine Reihe von Testfällen für unsere __/foos__-Ressource konfigurieren, indem wir __annotations__ wie folgt anwenden:
[source,javascript,gutter:,true]
----/foos:
type: myResourceTypes.collection
get:
(testCase):
scenario: No Foos
setupScript: deleteAllFoosIfAny
testScript: getAllFoos
expectedOutput: ""
(testCase):
scenario: One Foo
setupScript:[deleteAllFoosIfAny, addInputFoos] testScript: getAllFoos
expectedOutput: '[{ "id": 999, "name": Joe }]'
cleanupScript: deleteInputFoos
(testCase):
scenario: Multiple Foos
setupScript:[deleteAllFoosIfAny, addInputFoos] testScript: getAllFoos
expectedOutput: '[{ "id": 998, "name": "Bob" }, { "id": 999, "name": "Joe" }]'
cleanupScript: deleteInputFoos5. Fazit
In diesem Lernprogramm haben wir gezeigt, wie die Metadaten für eine RAML-API-Spezifikation durch die Verwendung von benutzerdefinierten Eigenschaften mit dem Namen annotations erweitert werden.
Zuerst haben wir gezeigt, wie man annotation types mithilfe der annotationTypes -Eigenschaft der obersten Ebene deklariert und die Typen der Zielspeicherorte aufgelistet, auf die sie angewendet werden dürfen.
Als Nächstes haben wir gezeigt, wie annotations in unserer API angewendet werden kann, und wir haben festgestellt, wie die Arten von Zielstandorten eingeschränkt werden können, auf die eine bestimmte annotation angewendet werden kann.
Schließlich haben wir einen potenziellen Anwendungsfall eingeführt, indem wir Annotationstypen definiert haben, die möglicherweise von einem Testgenerierungswerkzeug unterstützt werden, und zeigen, wie diese Annotationen auf eine API angewendet werden können.
Weitere Informationen zur Verwendung von annotations in RAML finden Sie unter RAML 1,0 spec .
Die vollständige Implementierung der für dieses Lernprogramm verwendeten API-Definition finden Sie unter https://github.com/eugenp/tutorials/tree/master/raml/annotations [the github project.
-
"** Bisherige