Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Render api specs #163

Draft
wants to merge 37 commits into
base: main
Choose a base branch
from
Draft

Render api specs #163

wants to merge 37 commits into from

Conversation

fabianrbz
Copy link
Collaborator

@fabianrbz fabianrbz commented Nov 28, 2024 •
edited
Loading

How it works

  • Similar to how they work in the docs, there’s an app/_api/ folder containing markdown files, each one of those is mapped to an API product in Konnect, and for each of them the platform generates a page (+ versions).
  • We use the new spec-renderer component pulling the specs from Konnect
  • api-specs folder containing API Specs for creating Run on Insomnia , error pages and and source of truth for Gateway EE and OSS Admin API specs.
  • The url structure is /api/<path-to-file>/<version>/ , so e.g. for app/_api/konnect/api-products/_index.md the url will be /api/konnect/api-products/ , /api/konnect/api-products/v2/ etc. ⚠️ Different to what we do in the docs., here everything is nested under the /api/.
  • No /latest/ for canonical urls
  • Gateway:
    • oss: drop patch from url, i.e /api/gateway/admin-oss/3.8/
    • ee: drop last digit from url, i.e. /api/gateway/admin-ee/3.8.0/
  • The Page title and description come from Konnect (same thing we render for the cards in /api/, we can overwrite these by setting them in the frontmatter)
  • Error pages (for specs that have x-errors) are generated too, although their urls are don’t have the version at the end /api/konnect/dev-portal/errors/ , /api/konnect/dev-portal/v2/errors/ - thoughts?

Notes

  • Styles need a ton of work, we haven’t really done any work on this, the plan is to ship it and work on that later - it actually looks better in light mode 🤷
  • Run on insomnia I need to refactor this at some point, so that we don’t have ugly urls everywhere. Need to talk to @Guaris about this
  • I haven’t set any metadata other than the content_type: reference , we can revisit this when we work on the search.
  • the layout is slightly wider (we can even go full-width) so that the spec is rendered in a two-column layout

Checklist

  • Every page is page one
  • Tested how-to docs. If not, note why here.
  • All pages contain metadata
  • Updated sources.yaml. For more info review track docs changes
  • Any new docs link to existing docs.

@netlify Netlify
Copy link

netlify bot commented Nov 28, 2024 •
edited
Loading

✅ Deploy Preview for kongdeveloper ready!

Name Link
🔨 Latest commit ddc50a4
🔍 Latest deploy log https://app.netlify.com/sites/kongdeveloper/deploys/67504ba75a64ec000847db90
😎 Deploy Preview https://deploy-preview-163--kongdeveloper.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

@fabianrbz fabianrbz added the ci:manual-approve:linting Mark link checking as successful label Nov 28, 2024
@fabianrbz
Add _api folder with the api specs and their corresponding product id in
66b01d0 
konnect
@fabianrbz
Render API spec pages
f131b40
@fabianrbz
Fix mobile styles on API specs
08a6809
@fabianrbz
Add some basic css variables for API specs
37ebf96
@fabianrbz
Move dev-portal and konnect-portal to the right subfolders
046bf08
@fabianrbz
WIP: Render api index page
ef23427
@fabianrbz
Add Run in Insomnia buttons to /api/
27e8a7b
@fabianrbz
Add api-specs folder
ca9375d
@fabianrbz
Update Run in insomnia links to point to the api specs in this repo
5b6fffb
@fabianrbz
Only show info_box if it is set
09e2079
@fabianrbz
Rename ssg_api_pages
93dbe74
@fabianrbz
Generate API error pages
cb2074c
@fabianrbz
Rename API canonical pages and add breadcrumbs to error pages
ff21736
@fabianrbz
Improve the layout of API pages
da39caa
@fabianrbz
Add breadcrumbs to API pages and fix some styles
94319ad
@fabianrbz
Use css classes for badges
0d6707b
@fabianrbz
Remove buttons from topnav and add link to /api
79414f2
@fabianrbz
Adjust with in api pages
cc238cb
@fabianrbz
Render a spinner when loading the api pages
7c402db
@fabianrbz
Render Versions dropdown on api pages
328da6a
@fabianrbz
Update links to gateway api pages
323423f
@fabianrbz
Update links to konnect api pages
1e7d33f
@fabianrbz
Update track-docs-changes source file
fd49e11
@fabianrbz
Handle missing flag in konnect-oas-data-generator gracefully
7255d51
@fabianrbz
Sync api products data with Konnect
b8e3171
@fabianrbz
Run workflows/linting on labeled
2582192
@fabianrbz
Fetch konnect_product_ids from the api_pages
2ab3881 
The entity_schema still references the api by url, the platform will
fetch the corresponding konnect_product_id for that url and render the
corresponding schema.
@fabianrbz
Rename latest to canonical
551d712
@fabianrbz
API pages: Always set the version in the URL, even for latest.
762c7fd 
Major versions don't change much (once per year max) and this also
provides consistent url structure with subpages.
@fabianrbz
Append the latest version to links that point to api_pages
ddc50a4
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
ci:manual-approve:linting Mark link checking as successful
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
1 participant
@fabianrbz