One Developer Portal to Document Them All

APIs in a modern enterprise are rarely uniform or all of the same type. The multitude of API types can be due to organic growth, mergers and acquisitions, or any number of other reasons. Once a company decides to fully manage and document their APIs, put emphasis on an API-first strategy, and streamline digital governance, they start looking for a developer portal that can support their needs. Customers often ask us whether Pronovix's Zero Gravity developer portal can document APIs that are not of the REST variety, such as AsyncAPI, GraphQL, SOAP, gRPC, and more. The short answer is, yes, the Zero Gravity (ZG) developer portal can document those too. Let's look at what is possible in a bit more detail with examples.

Types of APIs discussed in this article:

• REST APIs
• AsyncAPI
• GraphQL
• SOAP
• gRPC
• Everything Else

REST APIs

Out of the box, Zero Gravity developer portals support full featured documentation of REST APIs. The basis is provided via import of the OpenAPI specification (formerly known as Swagger), which is then interpreted and rendered by the SwaggerUI library. OpenAPI 2.x and OpenAPI 3.0 are fully supported, and OpenAPI 3.1 partially, limited by the current SwaggerUI library's capabilities. In Zero Gravity the SwaggerUI output is themed to match brand colors and styles and provides a cohesive look and feel throughout the developer portal.

For customers who prefer a three column layout, we can embed the Redoc library instead of SwaggerUI. It is important to note that the Redoc library lacks support for a Try Now feature.

To provide rich and complete documentation of REST APIs, Zero Gravity developer portals support the addition of related pages, such as a landing page with customizable and movable sections to describe the business value and features of an API and provide Call to Action links for developers to engage with. Other related pages could contain tutorials, terms and conditions, release notes, or any other content that is needed to fully document your API.

Three example pages illustrating the breadth of possible REST API documentation in the Zero Gravity developer portal. From left to right: Landing page, Example of SwaggerUI documentation, Additional information presented in the documentation (Tutorial). Click to open each in a new tab.

OpenAPI specification files can be manually added to create new or updated API documentation, or they can be uploaded via a CI/CD process by posting them from a version control system to an endpoint in the portal.

REST API documentation can include a Run in Postman button via the vendor extension x-postman-collection-id.

AsyncAPI

A strong new contender in the API space is AsyncAPI, a standardized way to build and provide tooling for event-driven and asynchronous APIs. Much like REST APIs have benefitted from standardization efforts, AsyncAPI does the same for event-driven APIs. AsyncAPI is protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, etc). One of the available tools, AsyncAPI Generator, generates documentation in HTML or Markdown from the AsyncAPI specification. With the MarkDown uploaded into the Zero Gravity developer portal (manually or via CI/CD process) and a few additional system adjustments - offered as a custom extension for now - we get a visually pleasing and technically correct and complete documentation page.

Just like for REST APIs, associated pages can be created to contain additional information about the AsyncAPI and its use to enrich and complete the documentation. Also, AsyncAPI specification files can be manually added to create new or updated API documentation, or they can be uploaded via a CI/CD process by posting them from your version control system to an endpoint in the portal.

GraphQL

Another newer API type is GraphQL. According to its creators, GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

As GraphQL, by its very definition, is a highly interactive interface, we have implanted the GraphQL playground IDE into the Zero Gravity developer portal. This provides the standard tool for developers to explore what data is available and allows them to zero in on the exact query they will need in their app. This solution is available as a custom feature in ZG.

SOAP

A much older, but still widely used API type is SOAP. With its highly structured, XML-based WSDL documentation file, SOAP is a highly opinionated way to build and document APIs.

In Zero Gravity, we have custom-built a bespoke SOAP documentation to benefit a customer in the financial sector, pictured below, and there is also the WSDL Docs contributed module available to render SOAP API documentation from a WSDL specification file. Both options are available as custom features. For the WSDL specification, manual upload and CI/CD-driven upload of the file is supported in ZG.
 

gRPC

In the microservices world, gRPC has become the standard way to build high performing and lightweight APIs. gRPC uses Protocol Buffer definition files for its schemas. There is an open source plugin available for the protoc compiler to render documentation in HTML, Markdown, and other formats.

In the Zero Gravity developer portal many fields accept (GitHub-flavored) Markdown, and hence it is possible to paste the generated Markdown into an API reference page to provide complete documentation of the gRPC interface. Adding the .proto file as a download completes the picture. gRPC support in ZG is therefore available out of the box. That said, a full featured implementation would likely entail a number of improvements to streamline the editorial and governance processes.

Everything Else

While REST, AsyncAPI, GraphQL, SOAP, and gRPC are the most widely used API types, there are of course many more API types in use, and more are added every year. For example, we have webhooks, OData, and JMS, just to name a few. Fortunately, most modern API ecosystems have tooling to output Markdown or HTML for documentation purposes. Using those formats, the Zero Gravity developer portal can easily accommodate the documentation and then provides its built-in complement of ancillary documentation pages to complete the picture.

Conclusion

As we have seen, a large variety of API types and protocols can be documented in the Zero Gravity developer portal in a straightforward and visually appealing way. Whether your organization uses just two, or a dozen different API protocols, we have you covered and can help you to provide complete documentation all in one developer portal. More importantly, we work with you to provide a good user experience to your developers and business users alike.