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

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 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 file

탐색 파일 편집

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

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

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

Create Navigation file

탐색 없음(apigit.json)

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