Documentazione dell'API JSON MVC

Question

Documentazione dell'API JSON MVC

#1 da (0 voti)

1

Ho un'applicazione MVC5 che stiamo utilizzando un'API JSON per vari client (app mobili, altre applicazioni Web, ecc.) e un'applicazione web tradizionale. Le azioni del controllore che restituiscono i dati JSON sono quelle che fanno parte dell'API.

La mia domanda è: qual è il modo migliore per documentare quali funzioni sono esposte? Sono nuovo di questa cosa dell'API, ma sembra che le persone debbano poter accedere e utilizzare l'API senza dover scavare nella base di codice.

Opzioni:

Wiki interno: ne abbiamo uno. Faccio un articolo che contiene tutte le funzioni che vengono esposte, e idealmente tenerlo aggiornato. Questo è l'approccio più semplice, ma meno gestibile secondo me. Chiunque aggiunga o modifichi una qualsiasi delle funzioni API dovrà tornare indietro e assicurarsi che questo articolo sia aggiornato.
Discovery endpoint - Un noto percorso API che fornisce una descrizione dell'applicazione auto-documentata (generata automaticamente?) che descrive i percorsi e le funzioni dell'API.
Qualche altro framework di cui non conosco?

api documentation .net json

posta ReimTime 08.05.2015 - 16:57

fonte

1 risposta

Leggi altre domande sui tag api documentation .net json

gestione degli eventi esterni in un ambiente cluster Non riesco a capire come parallelizzare il calcolo della quantità di prole prevista per le specie nell'algoritmo genetico

score 0 · Accepted Answer

Utilizziamo RAML che è un formato formalizzato per descrivere i tuoi servizi REST utilizzando YAML. Esempio:

title: World Music API
baseUri: http://example.api.com/{version}
version: v1
traits:
  - paged:
      queryParameters:
        pages:
          description: The number of pages to return
          type: number
  - secured: !include http://raml-example.com/secured.yml
/songs:
  is: [ paged, secured ]
  get:
    queryParameters:
      genre:
        description: filter the songs by genre
  post:
  /{songId}:
    get:
      responses:
        200:
          body:
            application/json:
              schema: |
                { "$schema": "http://json-schema.org/schema",
                  "type": "object",
                  "description": "A canonical song",
                  "properties": {
                    "title":  { "type": "string" },
                    "artist": { "type": "string" }
                  },
                  "required": [ "title", "artist" ]
                }
            application/xml:
    delete:
      description: |
        This method will *delete* an **individual song**

La sua natura formalizzata ha diversi vantaggi:

non è ambiguo (il che è spesso un problema con i normali documenti wiki non formattati)
può essere convalidato
può essere usato per creare uno scheletro di test automatici (c'è un plug-in SoapUI per questo)
può essere usato per generare (bella) documentazione - vedi ad es. link
può essere usato per generare client / codice server (in modo simile a come viene fatto in SOAP) - vedi link
puoi definire "tratto", ad es. impaginazione con parametri definiti che possono poi essere inclusi in più servizi web. Non è necessario duplicare la documentazione e ottenere API più coerenti.