JSON Objekte Dokumentieren

Alles, was nicht direkt mit Python-Problemen zu tun hat. Dies ist auch der perfekte Platz für Jobangebote.
Antworten
Benutzeravatar
veers
User
Beiträge: 1219
Registriert: Mittwoch 28. Februar 2007, 20:01
Wohnort: Zürich (CH)
Kontaktdaten:

Dienstag 3. März 2009, 08:43

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
[url=http://29a.ch/]My Website - 29a.ch[/url]
"If privacy is outlawed, only outlaws will have privacy." - Phil Zimmermann
lunar

Dienstag 3. März 2009, 08:55

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
User
Beiträge: 3018
Registriert: Montag 19. November 2007, 19:57
Wohnort: Kiel

Mittwoch 4. März 2009, 09:56

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
Antworten