Add API Documentations to the Website

[gemanor]

Important! This issue depends on the completion of #491

We want to add another tab to the docs website - API - which will have auto-generated pages based on our OpenAPI docs. The issue also includes some modifications/updates to the top Navbar on the website.

Requirements

• The API references should be embedded in the documentation website with the following plugin: https://github.com/PaloAltoNetworks/docusaurus-openapi-docs
• There are two sets of APIs to add to the docs
  • The Permit.io SaaS API - https://api.permit.io/v2/openapi.json
  • Permit's PDP APIs - https://pdp-api.permit.io/redoc
• Each of these API spec docs should have its own sidebar with all the available APIs
• In terms of menus, the existing sidebar should kept under a new navbar menu item, Docs, and each of the specs should be under new tabs in the new navbar
• Each API endpoint has a different page URL
• Every API page is SEO oriented with proper titles and descriptions for SEO purposes (the text should be taken from the OpenAPI)
• UI modifications of the navbar:
  • Move the search box to the middle
  • Remove the border between the Permit.io/Docs and the search box
  • Add a left menu with three items (docs, API Reference, PDP API) - the style should fit with our docs, and the layout should be similar to the attached Stripe navbar layout
  • Add a right menu with two items (homepage and help)
  • Replace the Twitter icon/link at the top with LinkedIn icon/link https://www.linkedin.com/company/permitio
  • The navbar on the desktop should look as the attached layout reference screenshot
  • The UI changes need to be carefully tested on desktop and mobile

Bounty Assignment

1. Before participating in this bounty, comment here with your detailed plan and timeline. We will not assign this issue if this information is missing. Please, DO NOT attempt the bounty before your proposal got accepted.
2. This task is on a first-come, first-served basis, but we will give it to the most promising/detailed proposal. There is an ask to avoid any GPT-generated proposals.

Navbar Layout Reference

[khabdrick]

Hello @gemanor
I am interested in working on this.

Phase 1: Starting with the low-hanging fruits (7th-12th Feb)

• Replace the Twitter icon/link at the top with LinkedIn icon/link at https://github.com/khabdrick/permit.io-docs/blob/master/docusaurus.config.js
• Position of the algolia searchbar https://github.com/khabdrick/permit.io-docs/blob/master/docusaurus.config.js
• Add openapi and theme-openapi-docs presets to docusaurus.config.js.
• Validate OpenAPI specs:
  • Permit.io SaaS API: https://api.permit.io/v2/openapi.json
  • PDP API: Convert Redoc spec to OpenAPI if needed (Not familiar with Redocly)
• Implement the specified navbar UI (I think I can do this in docusaurus.config.js also)

Phase 2: Embedding API docs (14-21st feb)

• Attach pages to the new navbar items
  • Documentation homepage under "Documentation"?
  • Permit.io SaaS API under /docs/api/permit-saas/
  • PDP API under /docs/api/permit-pdp/
• Embed the API references into your documentation website using the docusaurus-openapi-docs plugin
• Check meta tags (title, description) for API pages. Extract titles/descriptions from OpenAPI specs and set in each API’s .mdx files.
• Ensure OpenAPI description fields are rendered as page content.
• Final UI testing (desktop & mobile), make correction where needed

[khabdrick]

Hello @gemanor , any update here?