Api-blueprint: Erweitern von Datenstrukturen

Erstellt am 12. Nov. 2015  ·  6Kommentare  ·  Quelle: apiaryio/api-blueprint

Hallo, ich habe eine Frage/einen Vorschlag zu Datenstrukturen. Vielleicht hat das mehr mit MSON zu tun, aber ich fange hier an. Um die Datenstrukturen sauber zu halten, möchte ich so wenig doppelte Daten wie möglich, daher wäre es schön, wenn sich Datenstrukturen gegenseitig erweitern könnten.

Nehmen Sie die folgende Datenstruktur an:

# Data Structures

## Project_Link (object) 
+ self: `https://test.api.com/projects/5` (string, required)

## Project1_Get (object)
+ type: `projects` (string, required)
+ id: `5` (string, required)
+ attributes (object, required)
    + number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (Project_Link, required)

Im links Attribut von Project1_Get ich das Project_Link Objekt wieder, was super funktioniert. Aber angenommen, ich brauche auch die folgende Datenstruktur:

## Project1_Identifier (object)
+ type: `projects` (string, required)
+ id: `5` (string, required)

Jetzt gibt es doppelte Daten in meinen Datenstrukturen, weil Project1_Identifier das Attribut type und id , aber auch das Project1_Get . Es wäre toll, wenn ich folgendes machen könnte:

# Data Structures

## Project1_Link (object) 
+ self: `https://test.api.com/projects/5` (string, required)

## Project1_Identifier (object)
+ type: `projects` (string, required)
+ id: `5` (string, required)

## Project1_Get (Project_Identifier) <--- Extend!
+ attributes (object, required)
    + number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (Project1_Link, required)

Im folgenden Beispiel gibt Drafter Fehler zurück:

FORMAT: 1A
HOST: https://test.api.com/

# Test API
Hi, welcome to the API!

# Group Projects
Wow, we are using projects!

### Retrieve single project [GET /projects/{id}]
+ Parameters
    + id: `5` (string, required)

+ Response 200 (application/json)
    + Attributes (object)
        + data (Project1_Get, required)

# Data Structures

## Project_Link (object) 
+ self: `https://test.api.com/projects/5` (string, required)

## Project_Identifier (object)
+ type: `projects` (string, required)
+ id: `5` (string, required)

## Project1_Get (Project_Identifier)
+ type: `projects` (string, required)
+ id: `5` (string, required)
+ attributes (object, required)
    + number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (Project_Link, required)
user<strong i="25">@development</strong>:/srv/www/docs$ drafter -v
v2.0.0-pre.1
user<strong i="26">@development</strong>:/srv/www/docs$ drafter --validate docs.md --use-line-num

error: (4)  base type 'Project1_Get' is not defined in the document; line 16, column 11 - line 16, column 40
warning: (8)  unable to find the symbol `Project1_Get` in the list of named types; line 16, column 11 - line 16, column 40
Language Parser Implementation Bug

Hilfreichster Kommentar

@robbinjanssen Wenn Sie möchten, dass sie an der Spitze stehen, tun Sie bitte

## Project1Get
+ Include ProjectIdentifier
+ attributes (object, required)
    + number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (ProjectLink, required)

Alle 6 Kommentare

Dies sollte möglich sein. Scheint, als ob das Problem mit dem _ im Typnamen liegt. Das Umbenennen von Project1_Get in X schien zu funktionieren.

Hinweis _ ist ein reserviertes Zeichen pro MSON-Spezifikation – siehe https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#6 -reserved-characters--keywords

Ich glaube jedoch, dass wir hier in unserer Implementierung cc @pksunkara einen Fehler haben

Sie haben Recht, der Verfasser genehmigt jetzt den Abschlag anhand des folgenden Beispiels:

FORMAT: 1A
HOST: https://test.api.com/

# Test API
Hi, welcome to the API!

# Group Projects
Wow, we are using projects!

### Retrieve single project [GET /projects/{id}]
+ Parameters
    + id: `5` (string, required)

+ Response 200 (application/json)
    + Attributes (object)
        + data (Project1Get, required)

# Data Structures

## ProjectLink (object) 
+ self: `https://test.api.com/projects/5` (string, required)

## ProjectIdentifier (object)
+ type: `projects` (string, required)
+ id: `5` (string, required)

## Project1Get (ProjectIdentifier)
+ attributes (object, required)
    + number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (ProjectLink, required)

Aber in der Tat denke ich, dass es ein Fehler ist, sowohl aglio als auch die apiaryio-Schnittstelle rendern es falsch:

screen shot 2015-11-12 at 11 14 41

Bearbeiten: Hoppla, ich sehe, dass apiaryio es richtig rendert! Aber es platziert den Typ/die ID in diesem Fall unten. Ich bevorzuge es, es oben zu platzieren.

Ich warte, bevor ich meine Dokumente wieder überarbeite ;-)

@robbinjanssen Wenn Sie möchten, dass sie an der Spitze stehen, tun Sie bitte

## Project1Get
+ Include ProjectIdentifier
+ attributes (object, required)
    + number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (ProjectLink, required)

@pksunkara cool danke!

Ein einfaches Beispiel für den Fehler ist wie folgt:

# GET /projects

+ Response 200 (application/json)
    + Attributes (object)
        + data (B_B, required)

# Data Structures

## A_A
+ a: a

## B_B (A_A)
+ b: b

@zdne Ich denke, das hängt mit https://github.com/apiaryio/snowcrash/issues/335 zusammen. Was sagst du?

War diese Seite hilfreich?
0 / 5 - 0 Bewertungen

Verwandte Themen

alronlam picture alronlam  ·  4Kommentare

agougousis picture agougousis  ·  8Kommentare

pete001 picture pete001  ·  6Kommentare

fgblomqvist picture fgblomqvist  ·  3Kommentare

fh-thudson picture fh-thudson  ·  3Kommentare