Passen Sie die Navigation und Seitenleiste zum Veröffentlichen von Dokumenten an

APIGit

2025-03-12

Wenn Sie API-Spezifikationen und Markdown-Dokumente aus einem bestimmten Commit (SHA) eines Git-Repositorys veröffentlichen, um Ihre Dokumentationssite zu generieren, möchten Sie möglicherweise:

  • Definieren Sie das Layout der Dokumentationssite, einschließlich eines oberen Navigationsmenüs und Seitenleisten.
  • Geben Sie an, auf welche Dateien auf der veröffentlichten Dokumentationssite zugegriffen werden soll.

Diese Anpassungen können durch Hinzufügen einesapigit.jsonDatei in Ihr Repository. Hier ist ein minimales Beispiel:

{
	"nav": [
		{
			"name": "Getting Started",
			"slug": "getting-started",
			"children": [
				{
					"name": "Introduction",
					"slug": "introduction",
					"file": "docs/introduction.md"
				},
				{
					"name": "Installation Guide",
					"slug": "installation-guide",
					"file": "docs/installation.md"
				}
			]
		},
		{
			"name": "Features",
			"slug": "features",
			"group": [
				{
					"name": "User Management",
					"slug": "user-management",
					"children": [
						{
							"name": "User Registration",
							"slug": "user-registration",
							"file": "features/user-management/registration.md"
						},
						{
							"name": "User Authentication",
							"slug": "user-authentication",
							"file": "features/user-management/authentication.md"
						},
						{
							"name": "Profile Settings",
							"slug": "profile-settings",
							"file": "features/user-management/profile-settings.md"
						}
					]
				},
				{
					"name": "E-Commerce",
					"slug": "e-commerce",
					"children": [
						{
							"name": "Shopping Cart",
							"slug": "shopping-cart",
							"file": "features/e-commerce/shopping-cart.md"
						},
						{
							"name": "Checkout Process",
							"slug": "checkout-process",
							"file": "features/e-commerce/checkout.md"
						},
						{
							"name": "Order Tracking",
							"slug": "order-tracking",
							"file": "features/e-commerce/order-tracking.md"
						}
					]
				},
				{
					"name": "Reporting & Analytics",
					"slug": "reporting-analytics",
					"children": [
						{
							"name": "Dashboard Overview",
							"slug": "dashboard-overview",
							"file": "features/reporting/dashboard-overview.md"
						},
						{
							"name": "Sales Reports",
							"slug": "sales-reports",
							"file": "features/reporting/sales-reports.md"
						},
						{
							"name": "User Activity Logs",
							"slug": "user-activity-logs",
							"file": "features/reporting/user-activity-logs.md"
						}
					]
				}
			]
		},
		{
			"name": "API Reference",
			"slug": "api-reference",
			"children": [
				{
					"name": "Authentication",
					"slug": "authentication",
					"file": "api/authentication.json"
				},
				{
					"name": "Users",
					"slug": "users",
					"children": [
						{
							"name": "Get User",
							"slug": "get-user",
							"file": "api/users/get-user.json"
						},
						{
							"name": "Create User",
							"slug": "create-user",
							"file": "api/users/create-user.json"
						}
					]
				},
				{
					"name": "Orders",
					"slug": "orders",
					"children": [
						{
							"name": "Place Order",
							"slug": "place-order",
							"file": "api/orders/place-order.json"
						},
						{
							"name": "Cancel Order",
							"slug": "cancel-order",
							"file": "api/orders/cancel-order.json"
						}
					]
				},
				{
					"name": "Github",
					"slug": "github",
					"url": "https://github.com/apigitlabs/apigit-support"
				}
			]
		},
		{
			"name": "Guides",
			"slug": "guides",
			"children": [
				{
					"name": "Webhooks",
					"slug": "webhooks",
					"file": "guides/webhooks.md"
				},
				{
					"name": "Rate Limits",
					"slug": "rate-limits",
					"file": "guides/rate-limits.md"
				}
			]
		},
		{
			"name": "SDKs",
			"slug": "sdks",
			"children": [
				{
					"name": "JavaScript SDK",
					"slug": "javascript-sdk",
					"file": "sdk/javascript.md"
				},
				{
					"name": "Python SDK",
					"slug": "python-sdk",
					"file": "sdk/python.md"
				}
			]
		},
		{
			"name": "FAQ",
			"slug": "faq",
			"file": "docs/faq.md"
		},
		{
			"name": "Changelog",
			"slug": "changelog",
			"file": "docs/changelog.md"
		}
	]
}

Unten sehen Sie einen Screenshot, der veranschaulicht, wie die endgültige Navigation und Seitenleiste basierend auf den bereitgestelltenapigit.json Beispiel: APIGIT MockServer powered by expressjs and node

Navigationsdatei (apigit.json)

Aufbau der Navigationseinträge

Alle Navigationseinträge werden innerhalb dernavArray imapigit.jsonDatei. Hier ist eine Erklärung der verfügbaren Felder für jeden Eintrag:

  • Name (erforderlich): Der Anzeigename des Navigations- oder Seitenleisteneintrags.
  • Schnecke (optional): Eine URL-freundliche Kennung für den Eintrag. Wenn sie weggelassen wird, wird sie automatisch basierend auf dem Namen generiert.
  • Datei: Der Dateipfad zum spezifischen Dokument oder zur API-Spezifikation in Ihrem Repository.
  • URL: Die externe URL (Beispiel: „https://apigit.com“) des Navigationseintrags, der zu einer externen URL führt.
  • Kinder: Ein Array mit verschachtelten Einträgen, das Untermenüs und verschachtelte Seitenleisten ermöglicht.
  • Gruppe (nur oberste Ebene): Ein Array mit Einträgen für ein zweistufiges oberes Navigationsmenü.

Es gibt hauptsächlich vier Arten von Einträgen:

  • { name, slug, file }
  • { name, slug, url }
  • { name, slug, children }
  • { name, slug, group } (nur Navigation der obersten Ebene)

Erstellen einer Navigationsdatei

So erstellen Sie eine Navigationsdatei:

  1. Klicken Sie auf das Symbol „+“.
  2. Navigieren Sie zur Registerkarte „Navigation (apigit.json)“.
  3. Klicken Sie auf die Schaltfläche „Erstellen“.

Dadurch wird automatisch eine initiale Struktur für dieapigit.jsonDatei basierend auf der aktuellen Dateihierarchie Ihres Repositorys. Sie können diese anfängliche Struktur anschließend weiter anpassen.

Create Navigation file

Bearbeiten der Navigationsdatei

So bearbeiten Sie eine vorhandene Navigationsdatei:

  1. Wählen Sie dieapigit.jsonDatei aus Ihrem Repository.
  2. Bearbeiten Sie die Navigationseinträge direkt in unserem integrierten Editor.

Der Editor verfügt oben über eine hilfreiche Schaltfläche, mit der die Navigationsstruktur ähnlich wie beim anfänglichen Erstellungsprozess automatisch generiert werden kann und die einen praktischen Ausgangspunkt für weitere Bearbeitungen bietet.

Create Navigation file

ohne Navigation (apigit.json)

Wenn sich im Stammordner keine „apigit.json“ befindet und Sie API-Dokumente veröffentlichen, listen wir die API-Spezifikationsdateien und Markdown-Dokumente in alphabetischer Reihenfolge in einer Seitenleistenstruktur auf. So sieht das aus:APIGIT MockServer powered by expressjs and node