Typemark Documentation

OpenAPI-referents

Suuna Typemark OpenAPI-spetsifikatsioonile ja see koostab API-referentsi, mis koosneb ülevaatelehest ja ühest lehest iga lõpp-punkti kohta, iga avaldamise korral.

Uuendatud 19. nov 20263 min lugemist

Lisa oma repositooriumisse OpenAPI 3 või Swagger 2 spetsifikatsioon, viita sellele oma navigatsioonis ning Typemark genereerib sinu API-referentsi: ülevaatelehe ja ühe lehe iga lõpp-punkti kohta. Lehed koostatakse igal juurutamisel uuesti, seega jäävad need spetsifikatsiooniga sünkrooni.

Lisa oma spetsifikatsioon

  1. Aseta spetsifikatsioon oma repositooriumisse

    Kasuta JSON- või YAML-faili, näiteks openapi.json või openapi.yaml. Faile, mille laiend on .yaml või .yml, loetakse YAML-ina; kõiki teisi JSON-ina.

  2. Viita sellele failis typemark.json

    Lisa grupi pages juurde kirje koos source-ga, kasutades faili teed repositooriumi juurkataloogist:

    {
      "navigation": {
        "tabs": [
          {
            "tab": "API Reference",
            "groups": [
              {
                "group": "Endpoints",
                "pages": [{ "source": "openapi.json" }]
              }
            ]
          }
        ]
      }
    }
  3. Avalda

    Tee muudatus commitina. Järgmine ehitus genereerib lehed.

Projekti seadetest

Saad seda teha ka ilma typemark.json faili puutumata. Ava oma projekti seaded ja leia API Documentation.

  • Klõpsa Upload, et lisada .json-, .yaml- või .yml-fail. Typemark kontrollib, et tegemist on spetsifikatsioonifailiga, ning commitib selle repositooriumi juurkataloogi.
  • Või sisesta juba repositooriumis oleva spetsifikatsiooni tee.

Salvestamisel lisab Typemark spetsifikatsiooni rühma Endpoints vahekaardil API Reference, luues need vajadusel, ja koostab sinu saidi uuesti. Tühjenda väli ja salvesta, et genereeritud lehed eemaldada.

Mis genereeritakse

Ülevaatelehte

Ülevaatelehte kuvatakse navigatsioonis seal, kuhu panid source-kirje. Selle pealkiri tuleb spetsifikatsiooni väljalt info.title ning leht näitab:

  • info.description
  • versiooni väljalt info.version
  • baas-URL-i esimesest kirjest servers loendis
  • tabelit kõigist lõpp-punktidest koos meetodi, tee ja kokkuvõttega

Selle slug on spetsifikatsiooni failinimi ilma laiendita. Erand on fail nimega openapi, mille slug on api-reference.

Spetsifikatsiooni failÜlevaate slug
openapi.jsonapi-reference
specs/payments.yamlpayments

Lõpp-punkti lehed

Iga operatsioon GET, POST, PUT, PATCH ja DELETE saab oma lehe. Pealkiri on operatsiooni summary, või meetod ja tee, kui kokkuvõte puudub. Igal lehel kuvatakse:

  • meetod ja tee, koos sildiga Deprecated, kui operatsioon on aegunud
  • operatsiooni description
  • Parameters: nimi, asukoht, tüüp, kohustuslikkus ja kirjeldus
  • Request Body: kirjeldus ja application/json skeemi ülemise taseme omadused
  • Responses: üks jaotis iga olekukoodi kohta, koos kirjelduse ja selle application/json skeemi ülemise taseme omadustega

Lõpp-punkti slugid asuvad ülevaate slugi all ning ühendavad meetodi teega:

OperatsioonSlug
GET /usersapi-reference/get-users
POST /usersapi-reference/post-users
GET /users/{id}api-reference/get-users-id

Külgriba

Ülevaate leht ja kõik sildita lõpp-punktid on loetletud grupis, mis sisaldab sinu spetsifikatsiooni. Iga silt saab oma grupi, mis on nimetatud sildi järgi ja asub vahetult pärast seda; lõpp-punkt läheb oma esimese sildi gruppi. Iga külgriba link näitab HTTP-meetodit pealkirja kõrval.

Kuidas skeeme kuvatakse

SpetsifikatsioonisKuvatakse
$ref viide #/components/...Viidatud skeemi omadused
allOfKõigi alamskeemide omadused ühendatult
oneOf, anyOfTüübid ühendatud märgiga |, näiteks string | integer
enumLubatud väärtused, näiteks "active" | "archived"
MassiivElementide tüüp koos []-ga, näiteks string[]

Loetletakse ainult ülemise taseme omadused. Pesastatud objektid kuvatakse kui object.

Kirjuta lõpp-punkti leht

Kui lõpp-punkt vajab rohkem kui spetsifikatsioon ütleb, näiteks selgitust, kuidas voog töötab või millised makseviisid millele reageerivad, kirjuta sellele leht ja nimeta lõpp-punkt selle frontmatteris võtmega openapi:

---
title: Create a payment
openapi: "openapi.json POST /payment"
---

Card payments redirect the customer to their bank. Other methods answer at once.

Leht kuvab kõike, mida lõpp-punkti genereeritud leht kuvab, ning sinu tekst asub lõpp-punkti kirjelduse järel: meetod ja tee, kirjeldus, sinu tekst, seejärel Parameters, Request Body ja Responses. Muidu on see tavaline leht: sellel on oma aadress ja koht navigatsioonis ning see avaneb redaktoris nagu iga teine leht.

  • Spetsifikatsioon on tee repositooriumi juurkataloogist, nagu source-kirjes, või sinu docs_root järgi. Selle võib ära jätta (openapi: "POST /payment"): siis otsib Typemark spetsifikatsioone, mis on sinu navigatsioonis, järjekorras. Spetsifikatsioon ei pea olema navigatsioonis.
  • Meetod ja tee on kirjutatud täpselt nii nagu spetsifikatsioonis, näiteks GET /users/{id}.
  • Pealkiri on lõpp-punkti summary, kui lehel pole title-it, ja kirjeldus toimib samamoodi. Külgriba näitab meetodit pealkirja kõrval.
  • Kui Typemark lõpp-punkti ei leia, kuvab leht ainult sinu teksti ning juurutuse logis on hoiatus koos põhjusega. typemark check teatab sellest enne avaldamist.

Kui spetsifikatsioon on navigatsioonis ka { "source": ... } kaudu, jäävad selle genereeritud lehed alles, nii et sul on mõlemad. Ainult enda kirjutatud lehtede kuvamiseks jäta spetsifikatsioon navigatsioonist välja ja kirjuta leht iga lõpp-punkti jaoks. Mintlify'st ja ReadMe'st imporditud lehed kasutavad sama openapi-frontmatterit.

Näpunäited

  • Anna igale operatsioonile summary. See saab lehe pealkirjaks ja külgriba sildiks.
  • Märgi oma operatsioonid siltidega. Sildid muudavad pika lõpp-punktide loendi külgriba gruppideks, mida lugejad saavad kiiresti üle vaadata.
  • Hoia servers ajakohasena (Swagger 2 puhul host, basePath ja schemes). Esimene URL on ülevaatelehel kuvatav baas-URL.
  • Kui soovid mainida lõpp-punkti teisel lehel, kasuta lõpp-punkti rida. See viitab lõpp-punkti jaoks kirjutatud lehele või siis selle genereeritud lehele.
  • Eelvaata lehti enne avaldamist käsuga typemark dev, olles sisse logitud. typemark check leiab spetsifikatsiooni, mida ei saa parsida: avaldamine ebaõnnestuks koos veateatega.