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
Aseta spetsifikatsioon oma repositooriumisse
Kasuta JSON- või YAML-faili, näiteks
openapi.jsonvõiopenapi.yaml. Faile, mille laiend on.yamlvõi.yml, loetakse YAML-ina; kõiki teisi JSON-ina.Viita sellele failis typemark.json
Lisa grupi
pagesjuurde kirje koossource-ga, kasutades faili teed repositooriumi juurkataloogist:{ "navigation": { "tabs": [ { "tab": "API Reference", "groups": [ { "group": "Endpoints", "pages": [{ "source": "openapi.json" }] } ] } ] } }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
serversloendis - 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.json | api-reference |
specs/payments.yaml | payments |
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/jsonskeemi ülemise taseme omadused - Responses: üks jaotis iga olekukoodi kohta, koos kirjelduse ja selle
application/jsonskeemi ülemise taseme omadustega
Lõpp-punkti slugid asuvad ülevaate slugi all ning ühendavad meetodi teega:
| Operatsioon | Slug |
|---|---|
GET /users | api-reference/get-users |
POST /users | api-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
| Spetsifikatsioonis | Kuvatakse |
|---|---|
$ref viide #/components/... | Viidatud skeemi omadused |
allOf | Kõigi alamskeemide omadused ühendatult |
oneOf, anyOf | Tüübid ühendatud märgiga |, näiteks string | integer |
enum | Lubatud väärtused, näiteks "active" | "archived" |
| Massiiv | Elementide 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 sinudocs_rootjä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 poletitle-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 checkteatab 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
serversajakohasena (Swagger 2 puhulhost,basePathjaschemes). 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 checkleiab spetsifikatsiooni, mida ei saa parsida: avaldamine ebaõnnestuks koos veateatega.