JSON Objekte Dokumentieren

[veers]

Als Teil meiner Facharbeit muss ich ein JSON Interface Dokumentieren. Nun wie würdet ihr das tun? Ich habe derzeit etwas in der Art von:

Code: Alles auswählen

User = {
    Id: number,
    Name: string,
    Clocks: [Clock]
}

Clock = {
    Id: number,
    Name: string,
    Started: datetime
}

datetime = '\/Date(timestamp)\/'

Nicht gerade hübsch aber es erfüllt wohl seinen Zweck. Eine Alternative wäre eine Darstellung als Tabelle oder UML Klassen Diagram.


Jonas

[lunar]

Wieso dokumentierst du es nicht, wie du eine Python-Klasse dokumentieren würdest? Vom Konzept her besteht doch da imho kein großer Unterschied ...

[sma]

Die Typ-Notation ist letztlich egal, solange du sie erklärst oder formal definierst. Um den letzten Schritt nicht zu haben, könntest du dich auf eine andere Programmiersprache abstützen, in der du Strukturtypen definieren kannst und einfach auf deren Sprachdefinition verweisen. Eine Möglichkeit wäre hier ML. Oder du schaust bei EcmaScript 4, wie man dort hätte Typen definieren sollen.

Wenn die Typdefinition selbst JSON sein soll, könntest du dies machen:

Code: Alles auswählen

{
  "User": {
    "Id": "number",
    "Name": "string",
    "Clocks": ["Clock"]
  },
  "Clock": {
    "Id": "number",
    "Name": "string",
    "Started": "datetime"
  }
}

Während number, string, boolean sich ja aus der JSON-Spezifikation ergeben, muss man datetime noch definieren. Könnte man z.B. über einen regulären Ausdruck machen. Oder aber einfach sagen, es ist ein ISO8601-Datum in UTC-Form ohne optionale Teile von Jahr bis Sekunde. Oder so.

Stefan