게시 문서에 대한 탐색 및 사이드바 사용자 정의

APIGit

2025-03-12

Git 저장소의 특정 커밋(SHA)에서 API 사양과 마크다운 문서를 게시하여 문서 사이트를 생성하는 경우 다음을 수행할 수 있습니다.

  • 상단 탐색 메뉴와 사이드바를 포함한 문서 사이트의 레이아웃을 정의합니다.
  • 게시된 문서 사이트에서 어떤 파일에 접근할 수 있는지 지정합니다.

이러한 사용자 정의는 다음을 추가하여 달성할 수 있습니다.apigit.json파일을 저장소에 추가하세요. 다음은 최소한의 예입니다.

{
	"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"
		}
	]
}

아래는 제공된 내용에 따라 최종 탐색 및 사이드바가 어떻게 나타날지 보여주는 스크린샷입니다.apigit.json 예: APIGIT MockServer powered by expressjs and nodeAPIGIT MockServer powered by expressjs and node

탐색 파일(apigit.json)
탐색 항목의 구조

모든 탐색 항목은 다음 내에서 정의됩니다.nav배열에apigit.json파일. 각 항목에 사용 가능한 필드에 대한 설명은 다음과 같습니다.

  • 이름 (필수의): 탐색 또는 사이드바 항목의 표시 이름입니다.
  • 강타 (선택 과목): 항목에 대한 URL 친화적 식별자입니다. 생략하면 이름을 기반으로 자동 생성됩니다.
  • 파일: 저장소 내 특정 문서나 API 사양에 대한 파일 경로입니다.
  • url: 탐색 항목의 외부 URL(예: "https://apigit.com")은 외부 URL로 이동합니다.
  • 어린이들: 중첩된 항목을 포함하는 배열로 하위 메뉴와 중첩된 사이드바를 활성화합니다.
  • 그룹 (최상위 레벨만): 2단계 상단 탐색 메뉴에 대한 항목을 포함하는 배열입니다.

기본적으로 네 가지 유형의 항목이 있습니다.

  • { name, slug, file }
  • { name, slug, url }
  • { name, slug, children }
  • { name, slug, group } (최상위 탐색만 해당)
네비게이션 파일 생성

탐색 파일을 만들려면:

  1. "+" 아이콘을 클릭하세요.
  2. "탐색(apigit.json)" 탭으로 이동합니다.
  3. "만들기" 버튼을 클릭하세요.

이렇게 하면 자동으로 초기 구조가 생성됩니다.apigit.json저장소의 현재 파일 계층 구조에 따라 파일을 만듭니다. 그런 다음 이 초기 구조를 추가로 사용자 정의할 수 있습니다.

Create Navigation fileCreate Navigation file

탐색 파일 편집

기존 탐색 파일을 편집하려면:

  1. 선택하세요apigit.json저장소의 파일을 가져옵니다.
  2. 내장된 편집기에서 탐색 항목을 직접 편집하세요.

편집기 상단에는 초기 생성 과정과 비슷하게 탐색 구조를 자동 생성할 수 있는 유용한 버튼이 있어, 추후 편집을 위한 편리한 시작점을 제공합니다.

Create Navigation fileCreate Navigation file

탐색 없음(apigit.json)

루트 폴더에 apigit.json이 없는 경우, API 문서를 게시하면, API 사양 파일과 마크다운 문서를 알파 순서로 사이드 바 트리로 나열합니다. 다음과 같습니다. APIGIT MockServer powered by expressjs and nodeAPIGIT MockServer powered by expressjs and node