Import an OpenAPI spec

Generate API reference documentation from an OpenAPI 3.x specification file. Import is available on Pro, Team, and Business plans.

Before you begin #

• You need a Pro, Team, or Business plan

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

• Each endpoint becomes a separate topic, so large APIs generate many topics — plan your map structure accordingly

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. Review endpoint coverage. Each endpoint becomes a separate topic. Large APIs generate dozens of topics — plan your map structure accordingly.

3. Prepare supplementary content. The import generates reference documentation from the spec. You'll 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. Topicary parses the spec and shows preview cards for each endpoint or schema that will become a topic.

4. Click Import.

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, Topicary would create a topic for the GET /users endpoint containing the description, query parameter, and response schema.

What's generated #

Each API endpoint becomes a topic containing:

• 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)

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's 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

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 — verify 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 #

• Import formats — Full reference for all supported import formats, file size limits, and what content is preserved

• Create and manage topics — Edit and refine the generated endpoint topics after import

• Create and organize a map — Group imported API topics into a structured map with logical sections

• Publish a web site — Publish your API reference with Try It panels and method badges