Mastering Automation Through the Power of Documentation

McKenzie Tucci

September 22, 2023

We’ve said it before and we’ll say it again: Visible APIs get reused, not reinvented. Ensuring that developers can easily work with APIs is essential.

To make this happen, we need to provide them with clear documentation and helpful resources. That’s where SwaggerHub Portal comes in, simplifying the process and making it easier for developers to get the job done.

Why Portal?

SwaggerHub Portal API enables you to effortlessly productize your APIs. You can create a branded landed page with onboarding guides, resources, and documentation that help consumers both understand and integrate your APIs into their applications.

Now you can use our very own SmartBear Portal to automate the setup process and bring your portal to life. With the SwaggerHub Portal API, you can provide developers with a best-in-class Developer Experience (DX). They’ll benefit from a user-friendly interface and interactive documentation to accelerate API adoption.

Getting Started

Before diving into the specifics, here are a few prerequisites to get started:

SwaggerHub Account: You’ll need an enterprise license Swagger Hub account.
User Role: You need a designer or owner role within your SwaggerHub organization to invoke the APIs.
Enable SwaggerHub Portal: Swagger Hub Portal must be enabled for your organization.

With these prerequisites in place, you’re ready to automate the process of configuring your developer portal using SwaggerHub Portal APIs.

Authentication

To interact with the Portal APIs, you’ll need an API key from SwaggerHub. This API key should be included in the “Authorization” header as “Bearer [your_api_key]” for each API request you make.

Configuring Your Developer Portal

One of the first steps is to customize the appearance of your developer portal. While uploading brand images isn’t available through the API yet, you can set the accent color, fonts, and landing page description.

Get Portal Identifier: To manage your portal settings, you need to obtain the identifier for your portal instance using a call to the “portals” API resource.
Set Portal Settings: Utilize the obtained portal ID to update your portal’s settings through a PATCH request. You can adjust the accent color, fonts, and landing page description.

Adding Products

Products are essential components of your developer portal. You can manage product content, including API definitions and documentation, through Swagger Hub Portal APIs.

Create a Product: Send a POST request to the “products” endpoint to create a new product. Include the portal ID, product name, description, slug, and other relevant details.
Add a Logo: Add your company logo with ease to increase branding across your portal.

Populate Product Content

Once you’ve created a product, it’s time to populate it with content, including API definitions and documentation.

Create a Section: A section serves as a placeholder for content. Send a POST request to the “sections” endpoint, specifying the product’s section.
Add an API: Use a POST request to the section’s “table of contents” to add API references. Include the title, slug, and content (typically a reference to an OpenAPI definition).
Add Documentation: To provide comprehensive documentation, add Markdown documents alongside your technical API references. Send a POST request to the section, but this time with Markdown content.
Publish Content: Finally, publish the product content to make it accessible on your portal. Send a request to update the published content for the product.

What’s Next

Portal APIs enable you to streamline the configuration and management of your developer portal. Whether you’re adding products, updating content, or customizing the portal’s appearance, these APIs provide a powerful way to automate the process and enhance the developer experience.

With Portal, you can transform your empty developer portal into a user-friendly hub for your API documentation and resources. This self-serve approach empowers your development teams and accelerates API adoption.

Incorporate Portal APIs into your workflow today to supercharge your developer portal and provide developers with the tools they need to succeed. For a detailed, step-by-step setup guide, watch Getting Started with the SwaggerHub Portal API.

Try it out for free! {^widget|(htmlcode)%3clink+rel%3d%22canonical%22+href%3d%22https%3a%2f%2fsmartbear.com%2fblog%2fmastering-automation-through-the-power-of-document%2f%22%3e|(widget_displayname)Head+HTML+code|(name)HeadHTML|(width)|(height)^}