Modern API documentation approaches - OpenAPI, GraphQL, FastAPI, gRPC, and AsyncAPI

Table of contents

• OpenAPI specification and contracts
• FastAPI swagger documentation
• GraphQL schema documentation
• gRPC API documentation and specifications
• AsyncAPI for event-driven architecture
• Comparing documentation approaches
• Conclusion
• Ready to transform your API documentation?

Clear and comprehensive API documentation is vital for the success of software teams and businesses alike. This guide covers the leading tools for documenting modern APIs: Swagger, GraphQL schemas, FastAPI, gRPC, and OpenAPI. Learn the strengths and ideal use cases of each.

OpenAPI specification and contracts

The OpenAPI Specification (formerly known as Swagger) has become the de facto standard for RESTful API documentation. An OpenAPI contract is a formal definition of your API, typically written in YAML or JSON, that describes:

• Available endpoints and operations
• Operation parameters and authentication methods
• Contact information and terms of service
• Response schemas and examples

The OpenAPI contract serves as both documentation and a machine-readable specification that can be used to generate client libraries, server stubs, and interactive documentation UIs.

openapi: 3.0.0
info:
  title: Sample API
  description: Optional multiline or single-line description
  version: 0.1.9
paths:
  /users:
    get:
      summary: Returns a list of users
      responses:
        '200':
          description: A JSON array of user names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

The OpenAPI ecosystem includes tools like Swagger UI and Redoc, which generate interactive documentation from your specification. This approach is widely adopted because it creates a single source of truth for your API design.

FastAPI swagger documentation

FastAPI is a modern, high-performance web framework for building APIs with Python. One of its standout features is automatic interactive API documentation generation using OpenAPI and Swagger UI.

With FastAPI, documentation is generated from your code, which means:

• Documentation stays synchronized with your code
• Parameter validation rules are visible in the docs
• Interactive testing is available out of the box
• Authentication is integrated into the documentation

FastAPI uses Python type hints and docstrings to generate comprehensive API documentation:

from fastapi import FastAPI

app = FastAPI(
    title="My API",
    description="API description",
    version="0.1.0"
)

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
    """
    Retrieve an item by its ID.

    - **item_id**: The unique identifier of the item
    - **q**: Optional query string for filtering results
    """
    return {"item_id": item_id, "q": q}

This code automatically generates Swagger documentation accessible via the /docs endpoint, which includes:

• Interactive request builders
• Response schema definitions
• Authentication flows
• Example values

FastAPI Swagger documentation combines code-first development with comprehensive documentation, making it a favorite for Python developers building REST APIs.

GraphQL schema documentation

GraphQL takes a different approach to API documentation compared to REST-based systems. Instead of documenting endpoints, GraphQL is built around a strongly-typed schema that serves as both the contract and documentation for your API.

The GraphQL schema defines:

• Available queries and mutations
• Object types and their fields
• Relationships between types
• Input argument specifications

GraphQL schema documentation is typically presented through tools like GraphiQL or GraphQL Playground, which provide:

• Schema explorer interfaces
• Interactive query builders
• Real-time documentation
• Query validation and completion

Here’s an example of a GraphQL schema:

type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
}

type Query {
  user(id: ID!): User
  allUsers: [User!]!
  post(id: ID!): Post
}

The self-documenting nature of GraphQL means that clients can discover the API capabilities through introspection. This enables tools like GraphQL Playground to provide up-to-date documentation automatically, similar to how Swagger works for REST APIs but with a different paradigm focused on the data graph rather than endpoints.

gRPC API documentation and specifications

gRPC is a high-performance RPC (Remote Procedure Call) framework developed by Google. Unlike REST or GraphQL, gRPC uses Protocol Buffers (protobuf) as its Interface Definition Language (IDL) and data serialization mechanism.

Documentation for gRPC APIs centers around .proto files, which define:

• Service interfaces and methods
• Message structures and types
• RPC method parameters and return types

Here’s an example of a gRPC service definition:

syntax = "proto3";

package example;

service UserService {
  rpc GetUser (UserRequest) returns (UserResponse) {}
  rpc ListUsers (ListUsersRequest) returns (ListUsersResponse) {}
}

message UserRequest {
  string user_id = 1;
}

message UserResponse {
  string user_id = 1;
  string name = 2;
  string email = 3;
}

message ListUsersRequest {
  int32 page_size = 1;
  string page_token = 2;
}

message ListUsersResponse {
  repeated UserResponse users = 1;
  string next_page_token = 2;
}

While gRPC doesn’t have a built-in documentation system like Swagger for REST or GraphiQL for GraphQL, several tools have emerged to provide Swagger-like documentation for gRPC services:

• gRPC-Gateway: Generates OpenAPI specifications from protobuf definitions
• BloomRPC: A Postman-like GUI client for gRPC
• gRPCurl: A command-line tool for interacting with gRPC services
• gRPC-Web: Enables gRPC for web clients with documentation support

These tools help bridge the gap, providing gRPC documentation like Swagger, making complex protobuf definitions more accessible to developers.

AsyncAPI for event-driven architecture

While OpenAPI focuses on request-response APIs, AsyncAPI was developed specifically to document event-driven and message-based APIs. AsyncAPI is designed for architectures using protocols like MQTT, AMQP, Kafka, WebSockets, and other asynchronous communication methods.

AsyncAPI documentation defines:

• Message channels and topics
• Message payloads and schemas
• Publish/subscribe operations
• Server information and bindings

Here’s an example of an AsyncAPI document:

asyncapi: 3.0.0
info:
  title: Account Service API
  version: 1.0.0
  description: This service handles user account operations
channels:
  userSignedUp:
    address: user/signedup
    messages:
      userSignedUp:
        description: An event indicating that a new user has signed up
        payload:
          type: object
          properties:
            fullName:
              type: string
            email:
              type: string
              format: email
            age:
              type: integer
              minimum: 18
operations:
  onUserSignUp:
    action: send
    channel:
      $ref: '#/channels/userSignedUp'

AsyncAPI’s specification builds on concepts from OpenAPI but adapts them for event-driven scenarios. Tools in the AsyncAPI ecosystem include:

• AsyncAPI Generator: Creates documentation, code, and schema validation from AsyncAPI documents
• AsyncAPI Studio: A web-based editor for creating and validating AsyncAPI specifications
• AsyncAPI React: For building custom documentation interfaces

The AsyncAPI Initiative continues to grow, with major companies adopting the specification for their event-driven architectures. Newer versions of Swagger UI also provide support for displaying AsyncAPI documentation alongside OpenAPI documentation.

Comparing documentation approaches

Each API documentation approach has its strengths:

Feature	OpenAPI/Swagger	FastAPI	GraphQL	gRPC	AsyncAPI
Documentation Format	YAML/JSON	Python code + OpenAPI	GraphQL Schema	Protobuf	YAML/JSON
Interactive Testing	Yes (Swagger UI)	Yes (Swagger UI)	Yes (GraphiQL)	Limited (3rd party tools)	Limited
Code Generation	Extensive	Via OpenAPI	Yes	Built-in	Yes
Schema Validation	Yes	Yes	Yes	Yes	Yes
Learning Curve	Moderate	Low	Moderate	Steep	Moderate
Real-time Updates	Manual	Automatic	Automatic	Manual	Manual
Performance	Standard HTTP	Fast (ASGI)	Optimized queries	Very high	Protocol-dependent
API Paradigm	Request-Response	Request-Response	Query-based	RPC	Event-driven

Conclusion

Selecting the right documentation approach depends on your API technology and team preferences:

• OpenAPI specifications remain the industry standard for public-facing REST APIs
• FastAPI with Swagger documentation offers the most streamlined experience for Python developers building REST APIs
• GraphQL schema documentation provides excellent developer experience for data-focused APIs with complex relationships
• gRPC documentation through tools like gRPC-Gateway works well for high-performance microservices
• AsyncAPI specifications are ideal for event-driven architectures and message-based systems

The best API documentation is accurate, comprehensive, and maintainable. By understanding the strengths of each approach, you can choose the right tool for your specific needs and build APIs that developers love to use.

Remember that great documentation is an investment that pays dividends in developer satisfaction, reduced support costs, and successful API adoption. Whichever technology you choose, prioritizing documentation will lead to better developer experiences and more successful API products.

Ready to transform your API documentation?

Don’t let poor documentation hold back your API adoption! Weesho Lapara specializes in creating world-class API documentation systems for OpenAPI, FastAPI, GraphQL, gRPC, and AsyncAPI specifications. With over a decade of experience helping companies improve developer experience, Weesho can help you:

• Implement automated documentation workflows
• Create custom documentation portals
• Train your team on documentation best practices
• Audit and enhance existing API documentation

Book a free 30-minute consultation →

Transform your API documentation today and watch your developer adoption soar!