API documentation is the reference and guides that let a developer outside your company authenticate, call every operation and handle every failure without asking your team. For a SaaS company, a working first call is the easy part. The harder test is whether someone can build a native app on your docs alone, one that keeps running in hundreds of customer accounts through your next three releases.
That's the test your docs face once enterprise customers ask for an integration inside the CRM they already use. Their engineers read your docs, partners read them, and so does whoever builds your Salesforce or HubSpot app. Every gap they find turns into a support ticket repeated in each customer's account. An undocumented rate limit, for example, doesn't fail in testing. It fails the week your largest customer runs a backfill. Appnigma builds from API docs like these every week. "Build your product. We'll build the integrations," is how our done for you page puts it, with a named integration engineer and ongoing maintenance included. Our marketplace apps work puts "your product, inside Salesforce or HubSpot."
Updated October 2026. Checked against the OpenAPI Specification, the Diataxis framework, Postman's State of the API reports, HubSpot's listing requirements and Salesforce's developer docs. The earlier version called OpenAPI 3.1 the current version, dated the Swagger donation to 2016, quoted Postman figures we can't find in Postman's reports, and listed tool prices that have since changed. This update fixes those and adds which OpenAPI version Salesforce can import, what an integration builder checks in your docs, and the documentation marketplaces ask for.
Eight parts integration builders read first
API documentation usually covers eight parts, from authentication to a sandbox. Integration builders read them in a different order from first-time evaluators. They go to auth, errors and limits first, because those decide how much code the integration needs.
| Part | What it answers | What an integration builder looks for |
|---|---|---|
| Authentication | How does a caller prove who it is? | Whether each customer can connect through OAuth, or only through an API key pasted by an admin |
| Reference | Which operations exist, with which fields? | Every field, type and enum, including the ones only some plans have |
| Errors | What does each failure look like? | A stable error code per case, and which errors are safe to retry |
| Rate limits | How many calls, per what? | Whether the limit is per customer account, per app or per token, and the response sent when it's hit |
| Pagination | How do large lists come back? | Cursor or offset, the maximum page size, and whether order is stable |
| Webhooks | How does the API tell you something changed? | Signature verification, retry schedule and whether events can arrive twice |
| Changelog and versioning | What changed and when? | A deprecation window in writing, so a release in a customer's app isn't broken by surprise |
| Sandbox or test account | Where can you call it safely? | Test accounts a partner can create without a sales call |
Webhooks, versioning and test accounts are where most API docs are thin. They're also what an enterprise security or architecture review asks about before signing.
The four kinds of documentation, and which ones integrations need
The Diataxis framework names "four corresponding forms of documentation," per diataxis.fr. They are tutorials, how-to guides, technical reference and explanation. Most API companies pour effort into the tutorial, usually called a quickstart, because it's what evaluators see. Postman calls the speed of that first success time to first call, "the most important metric you'll need for a public API," in this post on time to first call.
An integration builder skips the quickstart and lives in the other three. They need reference complete enough to map every field, including the ones only some plans expose. They need how-to guides for the jobs a sync actually does, such as incremental fetches, backfills and secret rotation. And they need explanation of your data model and permission scopes, because that decides how the app maps your objects to Salesforce or HubSpot records. A strong quickstart with thin explanation wins the evaluation and then stalls the build.
API reference vs the OpenAPI specification
An API reference is the page people read, and the OpenAPI Specification is the YAML or JSON file that describes the same API for machines. The file is for machines, and for a SaaS API it's the more valuable of the two, because customers' platforms, SDK generators and integration builders consume the file directly. If the page and the file disagree, the file is what breaks.
Swagger is the old name. The spec's revision history records "Donation of Swagger 2.0 to the OpenAPI Initiative" on 31 December 2015, per the OpenAPI Specification v3.2.1, and the OpenAPI FAQ says it "became a separate project in 2016." Swagger now names SmartBear's tools, such as Swagger UI.
The latest OpenAPI release is 3.2.1, dated 10 September 2026. Version 3.2.0 came out on 19 September 2025, alongside patch 3.1.2, per the spec's revision history. Version 3.1 brought a real break from 3.0. Its Schema Object "is a superset of the JSON Schema Specification Draft 2020-12," per the 3.1.0 spec, and the OpenAPI-specific nullable keyword became redundant, per the 3.0 to 3.1 upgrade guide. Version 3.1 also added a top-level webhooks object for describing the events you send.
A minimal 3.0 description of one operation looks like this.
openapi: 3.0.3
info:
title: Acme API
version: "2026-10"
paths:
/contacts:
get:
operationId: listContacts
parameters:
- name: cursor
in: query
schema:
type: string
responses:
"200":
description: A page of contacts
"429":
description: Rate limit reached. Retry after the Retry-After header.Which OpenAPI version should a SaaS API publish?
Publish the newest version your own tooling supports, and also keep a 3.0.x copy. The reason is the platforms your customers use. Salesforce External Services, which turns an API description into actions admins can use in Flow and Apex, stores "the content of the OpenAPI 2.0.x or OpenAPI 3.0.x schema in JSON or YAML format," per the ExternalServiceRegistration reference (Winter '27). We found no Salesforce page that lists 3.1 or 3.2 for External Services. Data Cloud's Ingestion API has the same rule, "OpenAPI version 3.0.x is supported," per its schema requirements.
So a SaaS company that publishes only a 3.1 file has given its Salesforce customers a document they can't import directly. Someone has to convert it first, putting back the 3.0 nullable keyword wherever a type array allows null and dropping the webhooks section. Generating both files from one source in CI is usually a small job. Hand-converting for each customer isn't.
This matters even more when you ship a managed package. External Services registrations are packageable in both first- and second-generation managed packages and are updated during package upgrade, per Components Available in Second-Generation Managed Packages. The same page says "package developers must add named credential components to the External Services registration package." The registration's schemaUrl "must begin with "/" and be relative to the named credential endpoint," per the metadata reference. Your spec's server paths and your auth design therefore become part of the package. We cover the credential side in our named credentials guide.
Salesforce itself publishes a spec for part of its own API. Its sObjects REST API OpenAPI document "adheres to Version 3.0 of the OpenAPI Specification," and is a beta that Salesforce says not to build production integrations on, per Generating an OpenAPI 3.0 Document. HubSpot lists its OpenAPI spec files by API version in its developer docs index.
What an integration builder checks before building on your API
Whoever builds your native app, whether that's your team, a partner or Appnigma, works through the same questions before estimating. Each unanswered one becomes a call with your engineers or a guess that turns into a bug.
Start with how a customer connects. A marketplace app installs into many customer accounts, so the builder needs to know whether your API supports OAuth with per-customer tokens. If it only offers API keys, the setup screen has to ask an admin to paste a key, and someone has to document where that key lives. Next comes the limit model. A limit "per account" and a limit "per app across all accounts" call for very different sync designs once a few hundred customers install.
Then the change model. If you send webhooks, the docs need the signature scheme, the retry schedule and a statement on duplicates, so the app can deduplicate on an event ID. If you don't, the builder needs a reliable "updated since" filter, or every sync becomes a full scan. Our HubSpot webhooks guide shows what that looks like from the receiving side.
Last, the release model. A native app is versioned and installed, and customers upgrade on their own schedule. A field you rename without notice can break a version a customer installed months ago. A dated changelog and a written deprecation window are what let the app's maintainer plan releases.
Documentation the marketplaces ask for
The app marketplaces also review documentation. HubSpot's listing requirements ask for "a link to publicly available setup documentation specific to your HubSpot integration," per the App Marketplace listing requirements. Its setup guide rules say the guide must be "not hidden behind a paywall or sign-in screen" and must contain "the steps to install and configure the integration," per Create an app listing setup guide.
Salesforce's security review asks for similar material. Its required materials page says "we also ask for detailed solution user documentation and your company's information security policies," per Required Materials for Security Review Submission. If your app calls your own API, those endpoints need scanning too. "To scan external endpoints, use any Dynamic Application Security Test (DAST) scanner," per the scanner guidance. A clear list of every endpoint the app calls, taken straight from your spec, makes that scope easy to define. The practical lesson is to write the marketplace setup guide from the same source as your API docs. When the two are separate, reviewers and customers find the places where they disagree.
How to keep API documentation accurate
Docs go stale when they live apart from the code. The fix most API teams settle on is a single spec file kept in the same repository as the API, reviewed in the same pull request as the code change. Reference pages, SDKs and mock servers are generated from it on every merge. Tutorials, how-to guides and explanation stay hand-written in Markdown next to it, because no generator can write them.
Postman's surveys show why the discipline pays. In its 2024 report, "58% of developers rely on internal documentation, but 39% say inconsistent docs are the biggest roadblock," per the 2024 State of the API report. The same report says "good API documentation outranked performance or security" among factors in choosing an API.
Two checks catch most drift before it ships. First, run a contract test that calls a staging server and fails when a response doesn't match the spec. Second, keep every code sample in the docs as a runnable file that CI executes. A sample that no longer compiles fails the build instead of a customer's first try.
API documentation tools
Pick the spec workflow first and the tool second. Whatever renders your pages should read the same file your contract tests run against, or the docs drift again. Tools fall into renderers, hosted platforms that add guides and search, and SDK generators. Prices change often, so the table links each vendor's own page instead of quoting numbers.
| Tool | What it does | Notes |
|---|---|---|
| Swagger UI | Renders an OpenAPI file as interactive docs | Open source, from SmartBear |
| Redocly | Renderer, linter and hosted portal | Open source Redoc plus paid plans |
| Stoplight | Visual spec editor and hosted docs | Owned by SmartBear, paid plans only |
| Mintlify | Hosted docs-as-code platform | Free starter plan, paid plans |
| ReadMe | Hosted developer hub | Free starter plan, paid plans |
| Postman | API client with published collections as docs | Free, Solo and Team plans |
| Bump.sh | Hosted reference with change tracking | Paid plans |
| OpenAPI Generator | Generates SDKs and server stubs | Open source, "50+ client generators" |
For events and message-driven APIs, the equivalent of OpenAPI is AsyncAPI, "a project used to describe message-driven APIs in a machine-readable format," per the AsyncAPI specification.
Mistakes that break integrations after launch
These are the gaps that show up after an integration ships, when the docs stop matching what the API does.
- Plan-gated fields documented as if every customer has them, so the app fails in accounts on lower plans.
- Error responses that change shape between endpoints, so one retry handler can't cover them all.
- A rate limit described in a sentence but not in a response header, so clients can only guess when to back off.
- Webhook retries documented without saying events can repeat, so records get created twice.
- Breaking changes shipped under the same version string, which breaks installed app versions nobody upgraded.
- A spec published only in a version the customer's platform can't import.
Frequently Asked Questions
What is API documentation?
It's the reference, guides and machine-readable spec that let an outside developer build on an API without your team's help. For a SaaS API the test is whether a partner can ship a multi-customer integration from it, not just make one call.
What is the latest version of OpenAPI?
Version 3.2.1, dated 10 September 2026, is the latest release. Salesforce External Services still imports only OpenAPI 2.0.x or 3.0.x, so keep a 3.0.x copy if Salesforce customers will import your API.
Can Salesforce import an OpenAPI 3.1 file?
Not through External Services, which stores OpenAPI 2.0.x or 3.0.x schemas per its metadata reference. Generate a 3.0.x copy from the same source in CI and point Salesforce customers to that file.
What should API documentation include for integration partners?
Start with per-customer auth, every field and error code, and the rate limit model with its headers. Add pagination rules, webhook signatures and retries, a dated changelog with a deprecation window, and test accounts a partner can create alone.
Can Appnigma build our Salesforce or HubSpot integration from our API docs?
Yes. Our done for you team turns customer requests into working integrations against your API, with ongoing maintenance. For a listed app, marketplace apps covers the native app, listing preparation and review support.
Related Articles
- What a Native Salesforce App Is
- Salesforce Named Credentials and External Credentials
- HubSpot Webhooks Implementation Guide
- HubSpot API Rate Limits Guide
- Salesforce User Management REST API Documentation
- Salesforce Integration Tools
Sources
- OpenAPI Initiative, OpenAPI Specification v3.2.1
- OpenAPI Initiative, OpenAPI Specification v3.1.0
- OpenAPI Initiative, Upgrading from OpenAPI 3.0 to 3.1
- OpenAPI Initiative, FAQ
- Diataxis, A systematic approach to technical documentation
- Postman, 2024 State of the API Report
- Postman Blog, The most important API metric is time to first call
- Salesforce Developers, Metadata API Developer Guide, ExternalServiceRegistration
- Salesforce Developers, Data Cloud Integration Guide, Requirements for Ingestion API Schema File
- Salesforce Developers, Second-Generation Managed Packaging Developer Guide, Components Available in Managed Packages
- Salesforce Developers, REST API Developer Guide, Generating an OpenAPI 3.0 Document for sObjects REST API (Beta)
- Salesforce Developers, ISVforce Guide, Required Materials for Security Review Submission
- Salesforce Developers, ISVforce Guide, Source Code Scanner on the Portal
- HubSpot Developers, App Marketplace listing requirements
- HubSpot Developers, Create an app listing setup guide
- HubSpot Developers, docs index with OpenAPI specs
- AsyncAPI Initiative, AsyncAPI Specification
