Swagger – Basic Structure of the API Specification

In the ArcFM XI series universe, Swagger UI is more than just a reference – it’s a living map that guides the people building the software. Information architects and developers can quickly see how different parts of the system connect, test how they work, and spot issues early, without searching through site after site of technical documentation. That particular clarity and speed mean architects and developers can build features more confidently and efficiently. And when developers move faster with fewer surprises, users benefit too: the software becomes more reliable, more consistent, and easier to extend, giving utilities and partners tools on which they can build and trust.

When working within the ArcFM XI series ecosystem, understanding the basic structure of an Application Programming Interface (API), like the Swagger specification, can make it easier to explore how services are defined and connected. This structured “blueprint” allows Swagger UI to display a clear, interactive map of the system — helping developers, partners, and technical teams work with the API confidently and efficiently.

Version and Info – Identifying the Blueprint

At the top of the specification, the version and info fields define the foundation of the API:

The specification format version (e.g., swagger: "2.0")
Basic metadata, such as title, description, and API version

This ensures tools and teams are aligned on the same language and format for the API.

swagger: "2.0"
info:
  title: ArcFM XI API
  description: "Geospatial and utility services for ArcFM XI"
  version: "1.0.0"

Host, BasePath, and Schemes – Where to Find It

These fields specify where the API lives and how to access it:

host: The server address (e.g., api.schneider.com)
basePath: The root path for the API (e.g., /arcfm/v1)
schemes: Supported protocols (e.g., HTTPS)

Together, these elements form the complete address for each endpoint.

host: api.schneider.com
basePath: /arcfm/v1
schemes:
  - https

Consumes and Produces – Input and Output Formats

The consumes and produces fields define the data formats accepted and returned by the API. This ensures consistent communication between systems and services.

consumes:
  - application/json
produces:
  - application/json

Paths and Operations – Rooms and Entryways

The paths section outlines what the API can do. Each path represents an endpoint, and under each endpoint, operations (such as GET, POST, PUT, DELETE) define the actions available. Each operation can include:

A summary and description
Accepted parameters
Response types and status codes

Think of this as hallways and doors: each door tells you what to bring in (parameters) and what you’ll get back (responses).

paths:
  /stations:
    get:
      summary: "List all stations"
      responses:
        200:
          description: "Returns array of station objects"

Reusable Components – Design Once, Use Everywhere

Swagger lets you define common elements (such as models, parameters, or responses) once and reference them across multiple paths. This ensures consistency and reduces maintenance overhead.

definitions:
  Station:
    type: object
    properties:
      id:
        type: string
      name:
        type: string

paths:
  /stations/{id}:
    get:
      responses:
        200:
          description: "Single station"
          schema:
            $ref: "#/definitions/Station"

Why This Structure Matters for ArcFM XI

By organizing the API specification in this way, Swagger provides:

Faster collaboration for developers: Teams can quickly see how endpoints work, what data is required, and what is returned.
Consistency and maintainability: Updating a definition in one place automatically updates all references to it.
Early testing and validation: Mock servers and client libraries can be generated directly from the spec, allowing for earlier feedback and iteration.

Ultimately, this structured approach helps teams build more efficiently — and provides utility partners with software that’s more reliable, consistent, and ready to grow.