Skip to content

Import an OpenAPI spec

Generate API reference documentation from an OpenAPI 3.x specification file.

This feature requires the Team capability tier (the Team or Business ). During the beta, every project is on the free Solo tier, so this feature is locked by default: go to Settings ▸ Billing and request Team access to unlock it.

Before you begin

  • You need a Team or Business plan

  • Your spec must be valid OpenAPI 3.x (JSON or YAML). Topicary does not support Swagger 2.0 or earlier

  • Endpoints are grouped into topics by their OpenAPI tag, plus one overview topic, so a spec with many tags generates many topics

Plan your import

  1. Validate your spec first. Topicary supports OpenAPI 3.x (JSON or YAML). Ensure your spec parses without errors before importing.

  2. Tag your operations. Endpoints are grouped into topics by their first OpenAPI tag: every operation that shares a tag lands in the same topic. Operations with no tag are grouped by the leading segment of their path. Tag your spec the way you want the docs divided before importing.

  3. Prepare supplementary content. The import generates reference documentation from the spec. You will likely want to add getting-started guides, authentication overviews, and usage examples as separate topics.

Import the spec

  1. Go to Topics and click Import.

  2. Select a .json or .yaml OpenAPI 3.x specification file.

  3. A preview card shows the spec's title, version, and an OpenAPI format badge.

  4. Click Import. Topicary generates an overview topic plus one topic for each tag.

Here is an example of a minimal OpenAPI spec that Topicary can import:

openapi: 3.0.3
info:
  title: Acme API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      description: Returns a paginated list of users.
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email

In this example, the GET /users operation has no tag, so Topicary groups it under a topic derived from the path (users). That topic documents the operation's description, query parameter, and response schema, alongside an overview topic for the API itself.

What is generated

The import always creates an overview topic (the API title, base URL, which is the first server in the spec, version, and contact), followed by one topic for each tag. Each tag topic documents all of its operations, with each operation showing:

  • Endpoint path and HTTP method

  • Description from the spec

  • Request parameters (path, query, header)

  • Request body schema

  • Response schemas by status code

  • Example requests and responses (if present in the spec)

Include example fields in your OpenAPI spec before importing. Topicary uses these to generate request and response samples in each topic, which saves you from writing them manually after import.

Published site features

When published, API reference topics benefit from additional features:

  • Method badges: GET, POST, PUT, DELETE badges with color coding

  • Try It panels: interactive API explorer for testing endpoints directly from the docs

  • Code blocks: formatted request and response examples with copy buttons

What is not preserved

  • Deprecated endpoint flags: present in generated content as text, but not visually flagged

  • Complex schema composition (allOf, oneOf, anyOf): flattened into a single description

  • Webhooks: not imported

  • Server variables and multiple server URLs: first server used; others ignored

  • Authentication schemes: described in text, but not wired into the Try It explorer's auth header field

Complex schema composition using allOf, oneOf, and anyOf is flattened during import. If your API relies heavily on composed schemas, review the generated topics to ensure the flattened descriptions are accurate and complete.

Post-import checklist

  1. Review generated topics for completeness. Check that parameter descriptions and response schemas transferred.

  2. Organize the topics in a map with logical grouping (by resource, by workflow, or by area).

  3. Add supplementary content: a getting-started guide, authentication overview, and common use-case examples.

  4. Publish and test the Try It explorer panels, verifying that endpoints are reachable and responses display correctly.

  5. If your API requires authentication, document how readers should use the Authorization header field in the Try It panel.

See also

Was this page helpful?