About this example

This is an example by Stephen Mizell on how you could use Next.js and MDX to build a customizable API Developer Portal. It shows how you can use Redoc and Swagger UI directly in a project like this to include not only access to the API reference, but also documentation related to using the API. View this code on GitHub.

Why an OpenAPI file isn't enough

An API Developer Portal is more than viewing an OpenAPI file. An OpenAPI file tells people the technical details for using an API—what URLs to use, what HTTP methods to use, and the models for the API. There is much more to the API experience than that.

An API Developer Portal should include things like:

• A "Getting started" page that helps people go from nothing to using the API as quickly as possible
• Information about authentication and authorization
• Links to tools like CLIs and SDKs
• Links to status pages
• Details on how to get in touch with support
• Reasons why someone would use the API
• Examples on how someone might use the API
• What's planned and what's changed recently

This is all in addition to an OpenAPI file—which I'm calling an API Reference in this example project—and any other helpful information like Postman Collections.

You can view this about page on GitHub.

What's missing

Good developer portals have good navigation. This would include breadcrumbs and sidebars that let people explore the documentation. Next.js doesn't do this for you out of the box, so it would require some work there.

This also does not include authentication, which might be necessary if you need to keep your documentation private. There are some packages for Next.js to make this possible. This example here does not use them, though.