Why documentation matters

Documentation is the first thing a developer sees and often the deciding factor in whether they adopt your API. Well-documented APIs reduce support requests, shorten integration time, and build trust. On the PSA Developer Portal, your documentation is generated directly from your OpenAPI specification, so the spec is the single source of truth.

Start with an OpenAPI specification

Describe every API with an OpenAPI 3.0 or 3.1 document. A complete spec includes:

• Info – A clear title, version, and a short description of what the API does and who it is for.
• Servers – The base URLs for each environment (for example, sandbox and production).
• Paths and operations – Every endpoint, with a summary, description, and a unique operationId.
• Parameters and request bodies – Types, formats, whether each is required, and allowed values.
• Responses – Every status code the API can return, including error responses.
• Security – How callers authenticate, such as API key or OAuth 2.0.

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
  description: Create and manage customer orders.
servers:
  - url: https://api.example.com/v1
paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Retrieve an order
      description: Returns a single order by its unique identifier.
      parameters:
        - name: orderId
          in: path
          required: true
          description: The unique identifier of the order.
          schema:
            type: string
      responses:
        "200":
          description: The requested order.
        "404":
          description: No order exists with the given identifier.

Write for the reader

• Lead with purpose. Start each description with what the operation does, then add details and constraints.
• Be specific. Document formats, limits, defaults, and units (for example, "ISO 8601 date" or "maximum 100 items").
• Use consistent terms. Choose one name for each concept and use it everywhere.
• Explain errors. For each error response, say what caused it and how to resolve it.
• Keep it current. Update the spec in the same change that updates the API.

Add examples

Examples are often the most useful part of the documentation. Include a realistic request and response for each operation, and show both success and common error cases. Avoid real customer data; use clearly fictional values.

{
  "id": "ord_1042",
  "status": "shipped",
  "total": 59.99,
  "currency": "USD"
}

Document authentication

Explain how to get credentials and how to send them. Cover how to register an application, which scopes or permissions are required, how tokens are passed in requests, and how to handle expired or invalid credentials. Link to the Getting started page for the registration steps.

Review before you publish

Use this checklist before publishing or updating an API:

1. The spec validates with no errors or warnings.
2. Every operation has a summary, description, and operationId.
3. Every parameter and schema property has a description.
4. All success and error responses are documented, with examples.
5. Authentication requirements are described.
6. Descriptions have been proofread for clarity and spelling.

Next steps

Once your documentation is complete, move on to Publish APIs to make it available to developers.