When you publish API specifications and Markdown documents from a specific commit (SHA) of a git repository to generate your documentation site, you might want to:
- Define the layout of the documentation site, including a top navigation menu and sidebars.
- Specify which files should be accessible on the published documentation site.
These customizations can be achieved by adding an apigit.json file to your repository. Here's a minimal example:
{
"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"
}
]
}
Below is a screenshot illustrating how the final navigation and sidebar might appear based on the provided apigit.json example:
Navigation File (apigit.json)
Structure of Navigation Entries
All navigation entries are defined within the nav array in the apigit.json file. Here's an explanation of the available fields for each entry:
- name (required): The display name of the navigation or sidebar entry.
- slug (optional): A URL-friendly identifier for the entry. If omitted, it will be automatically generated based on the name.
- file: The file path to the specific document or API specification in your repository.
- url: The external url (example:"https://apigit.com") of the naviation entry,which will lead to jump to an external url.
- children: An array containing nested entries, enabling submenus and nested sidebars.
- group (top-level only): An array containing entries for a two-level top navigation menu.
There are primarily four types of entries:
{ name, slug, file }{ name, slug, url }{ name, slug, children }{ name, slug, group }(top-level navigation only)
Creating a Navigation File
To create a navigation file:
- Click the "+" icon.
- Navigate to the "Navigation (apigit.json)" tab.
- Click the "Create" button.
This automatically generates an initial structure for the apigit.json file based on your repository's current file hierarchy. You can then customize this initial structure further.
Editing the Navigation File
To edit an existing navigation file:
- Select the
apigit.jsonfile from your repository. - Edit the navigation entries directly within our built-in editor.
The editor includes a helpful button at the top that can auto-generate the navigation structure, similar to the initial creation process, providing a convenient starting point for further edits.
without navigation (apigit.json)
when there is no apigit.json in the root folder, when you publish api documents, we will list out api spec files and markdown documents in its alpha order as a side bar tree. here is how it look like.
Related Posts
what are the components of an api
This article explains the different components of a REST API by following a request from end to end. An API client is responsible for assembling and directing an API request to the API server. An API request to a REST API consists of an endpoint, method, parameters, request headers, and a request body. The API server handles authentication, validates input data, retrieves or manipulates data from a database, and returns the appropriate response to the client. An API response typically includes a status code, response headers, and a body. API status codes are used to provide information to the client about the outcome of the request and to help the client understand how to proceed. Response headers and bodies provide additional information and data about the response.
View API documents in different modes
APIGit suports different viewer modes for an API documents. it is easy for you to switch viewers among of them
Secure Your Digital Doorways: Comprehensive API Security Best Practices
Protect your APIs with strong authentication, authorization, data encryption, rate limiting, input validation, and regular security testing to prevent unauthorized access and data breaches.
Ready to get started with APIGIT?
Join thousands of developers and teams who are already using APIGIT to streamline their API development workflow.