Swagger 2.0, OpenAPI and Custom Connectors in Microsoft Power Platform and Copilot Studio

A Practical Guide Using the Open-Meteo Weather API

Introduction

Modern business applications rarely operate in isolation.

A Power Apps application might need weather information. A Power Automate flow might need to call an external service. A Copilot Studio Agent might need real-time information that doesn’t exist in its configured Knowledge Sources.

In all these scenarios, an external REST API can become part of the architecture.

The challenge is that an API exposes technical concepts such as:

• HTTP endpoints
• HTTP methods
• Query parameters
• Headers
• Authentication
• Request bodies
• Response bodies
• JSON schemas
• Status codes

Microsoft Power Platform needs a structured description of these elements before it can expose an API conveniently as operations that makers can use.

One important mechanism for providing this description is OpenAPI.

Historically, OpenAPI was known as Swagger.

For Microsoft Power Platform Custom Connectors, OpenAPI 2.0 / Swagger 2.0 remains particularly important.

This article develops a complete mental model:

API

→ Swagger / OpenAPI definition

→ Custom Connector

→ Connection

→ Power Apps / Power Automate / Copilot Studio

We will use the public Open-Meteo weather API as our practical example.

1. Start with the REST API

Before discussing Swagger, we need to understand what Swagger describes.

Consider the Open-Meteo Forecast API.

Its basic endpoint is:

The API can receive geographical coordinates such as:

latitude

longitude

and weather variables.

A simplified request could conceptually look like:

GET /v1/forecast?latitude=-23.55&longitude=-46.63&current=temperature_2m

The API processes the HTTP request and returns JSON.

Conceptually:

Client

→ HTTP GET

→ Open-Meteo API

→ JSON

→ Client

This is a standard REST integration.

The API itself already works without Swagger.

That distinction is important:

Swagger does not create the API.

Swagger describes the API.

2. What Is Swagger?

Swagger originated as a specification and ecosystem for describing REST APIs.

The specification eventually became the OpenAPI Specification.

Therefore, when people say:

Swagger 2.0

they are usually referring to:

OpenAPI Specification 2.0

A Swagger/OpenAPI document is a machine-readable contract describing an API.

Instead of explaining an API only through human documentation such as:

“Send latitude and longitude to this URL using GET”

we can describe the same contract structurally.

For example:

swagger: “2.0”

host: api.open-meteo.com

basePath: /v1

schemes:

• https

paths:
/forecast:
get:
…

A system can read this file and understand that an HTTPS API exists at:

api.open-meteo.com

with an operation:

GET /v1/forecast

3. Swagger as an API Contract

A useful mental model is:

REST API = implementation

Swagger = contract

Connector = adapter

Connection = configured runtime access

Power Apps / Power Automate / Copilot Studio = consumers

Therefore:

Open-Meteo API

↓

Swagger 2.0

↓

Power Platform Custom Connector

↓

Connection

↓

Power Apps / Power Automate / Copilot Studio

This distinction will become increasingly important when working with enterprise APIs.

4. What Does Swagger Describe?

A Swagger document can describe several characteristics of an API.

Swagger is therefore much more than a list of URLs.

It describes the interface contract between systems.

5. The Basic Swagger 2.0 Structure

A minimal document begins with:

swagger: "2.0"

This tells the consumer:

“This document follows the Swagger/OpenAPI 2.0 specification.”

Then we normally define metadata:

info:
  title: Open-Meteo Weather API
  description: Weather forecast API integration
  version: "1.0"

This information doesn’t execute anything.

It describes the API.

6. The Host

Next:

host: api.open-meteo.com

The host identifies the server.

Notice that we don’t write:

https://api.open-meteo.com

The protocol belongs to another property:

schemes:
  - https

Conceptually:

scheme + host

becomes:

7. Base Path

Open-Meteo exposes the forecast endpoint under:

/v1/forecast

We can separate this into:

basePath: /v1

and:

paths:
  /forecast:

The resulting URL becomes:

This decomposition is important because many APIs expose multiple operations below a common base path.

For example:

/v1/forecast

/v1/archive

/v1/climate

The base portion can be represented once.

8. The paths Section

The heart of an OpenAPI definition is usually:

paths:

Inside it we describe operations.

For example:

paths:
  /forecast:
    get:

This means:

Endpoint:

/forecast

Method:

GET

Combined with the previous properties:

schemes:
  - https
host: api.open-meteo.com
basePath: /v1

the complete request becomes:

GET https://api.open-meteo.com/v1/forecast

9. HTTP Methods

Swagger describes REST operations using HTTP verbs.

The most common are:

Open-Meteo’s forecast request is a good GET example because we are retrieving information without modifying the remote system.

This is useful when learning integrations because it gives us a relatively safe, read-only operation.

10. operationId

One extremely important property for Power Platform is:

operationId: GetWeatherForecast

The operationId provides a unique programmatic identity for the operation.

Human documentation might describe the operation as:

“Get Weather Forecast”

but Power Platform needs a stable technical identifier.

Conceptually:

REST endpoint

GET /forecast

↓

Swagger

operationId = GetWeatherForecast

↓

Custom Connector

GetWeatherForecast

↓

Power Apps / Power Automate / Copilot Studio

This becomes particularly important once a connector contains multiple operations.

For example:

GetCurrentWeather

GetForecast

GetHistoricalWeather

GetMarineWeather

Each operation needs a clear identity.

11. Summary and Description

An operation can include:

summary: Get weather forecast

and:

description: Returns weather forecast data for a geographical location.

These descriptions are not merely cosmetic.

They help humans understand the operation and become increasingly important in agentic architectures because clear descriptions help orchestration understand what capabilities are available.

For example, a Copilot Studio Agent might have several Tools:

GetWeatherForecast

CreateSharePointRequest

GetEmployeeProfile

SendEmail

Good descriptions make the semantic purpose of each Tool clearer.

12. Parameters

The Open-Meteo forecast endpoint requires geographical coordinates.

Two fundamental parameters are:

latitude

longitude

The official Open-Meteo documentation defines these as geographical WGS84 coordinates.

In Swagger:

parameters:
  - name: latitude
    in: query
    required: true
    type: number
    format: double
    description: Latitude of the requested location.
  - name: longitude
    in: query
    required: true
    type: number
    format: double
    description: Longitude of the requested location.

This is one of the most important parts of the contract.

13. Understanding in: query

Consider:

name: latitude
in: query

in: query means that the value is placed in the query string.

Therefore:

latitude = -23.55

becomes:

?latitude=-23.55

Adding longitude produces:

?latitude=-23.55&longitude=-46.63

Swagger allows parameters to exist in different locations.

Understanding parameter location is essential when designing Custom Connectors.

14. Required vs Optional Parameters

Consider:

required: true

This means that the operation requires the parameter.

For Open-Meteo:

latitude = required

longitude = required

Other parameters can be optional.

For example:

- name: timezone
  in: query
  required: false
  type: string

This allows Power Platform to understand which inputs must be supplied.

15. Data Types

Swagger 2.0 supports fundamental types such as:

• string
• number
• integer
• boolean
• array
• object

Our coordinates are numbers:

type: number
format: double

An API parameter representing the number of forecast days might instead use:

type: integer

A true/false option could use:

type: boolean

Correct typing matters because Power Platform can use the schema to validate and expose inputs appropriately.

16. Open-Meteo Weather Variables

Open-Meteo allows clients to select weather variables.

Examples include information related to:

temperature

precipitation

wind

humidity

weather conditions

This is interesting architecturally because APIs frequently allow clients to control which fields are returned.

Instead of always returning a massive dataset, the consumer asks for what it needs.

For an Agent we might want only:

current temperature

wind speed

weather condition

For a Power Apps weather dashboard we might request additional hourly or daily information.

The API contract should therefore expose only the parameters that are useful to the business scenario rather than automatically exposing every possible API option.

17. Responses

Swagger also describes what comes back.

A basic response definition might be:

responses:
  "200":
    description: Successful weather response
    schema:
      type: object

HTTP status 200 means the request succeeded.

Other APIs might define:

A robust API contract should document relevant responses rather than assuming that every call succeeds.

18. Response Schema

A major advantage of OpenAPI is the ability to describe the structure of returned JSON.

Imagine a simplified response:

{
  "latitude": -23.55,
  "longitude": -46.63,
  "timezone": "America/Sao_Paulo",
  "current": {
    "temperature_2m": 22.5,
    "wind_speed_10m": 11.4
  }
}

Swagger can describe this structure.

Conceptually:

schema:
  type: object
  properties:
    latitude:
      type: number
    longitude:
      type: number
    timezone:
      type: string
    current:
      type: object
      properties:
        temperature_2m:
          type: number
        wind_speed_10m:
          type: number

Now Power Platform doesn’t merely know:

“Some JSON comes back.”

It knows the expected structure.

19. Why Response Schemas Matter

Without a schema:

API

↓

Unknown JSON blob

With a schema:

API

↓

Structured object

↓

Properties

↓

Power Platform fields

This makes integration considerably easier.

Power Apps can work with properties.

Power Automate can expose dynamic content.

Copilot Studio can receive structured Tool outputs.

The schema therefore acts as a bridge between raw HTTP and low-code development.

20. definitions

Swagger 2.0 also allows reusable schemas under:

definitions:

For example:

definitions:
  CurrentWeather:
    type: object
    properties:
      temperature_2m:
        type: number
      wind_speed_10m:
        type: number

An operation can reference it using:

$ref: "#/definitions/CurrentWeather"

This becomes particularly useful in larger APIs.

Without reusable definitions, the same object schema might need to be repeated many times.

21. Authentication

Authentication is one of the most important subjects when moving from a learning API to enterprise integrations.

APIs may use:

• No authentication
• API key
• Basic authentication
• OAuth 2.0
• Microsoft Entra ID / OAuth
• Bearer tokens
• Other proprietary mechanisms

Open-Meteo is convenient for learning because its public API can be used for our basic example without introducing an authentication mechanism first.

This allows us to isolate the concept:

Swagger → Connector → API

before adding:

Identity → Credentials → Tokens → Authorization

That separation is useful pedagogically.

22. Swagger Security Definitions

Suppose another API required an API key.

Swagger 2.0 could contain something conceptually like:

securityDefinitions:
  apiKey:
    type: apiKey
    name: X-API-Key
    in: header

Then:

security:
  - apiKey: []

Now the contract says:

“This API requires an API key supplied through the X-API-Key header.”

Power Platform can use that information when creating the connector authentication configuration.

23. OAuth 2.0

Enterprise APIs frequently use OAuth.

Conceptually:

User / Application

↓

Identity Provider

↓

Authentication

↓

Access Token

↓

Connector

↓

API

In Microsoft environments, Microsoft Entra ID frequently participates in this architecture.

Later in our learning path this becomes:

App Registration

→ OAuth

→ scopes

→ Delegated permissions

or

→ Application permissions

→ token

→ API

This is considerably more sophisticated than our Open-Meteo example, so it should be treated as a separate architectural layer.

24. Swagger vs Authentication

An important distinction is:

Swagger describes how authentication works.

Swagger itself does not authenticate the user.

Similarly:

Custom Connector knows how authentication should occur.

Connection stores or represents the configured authentication context.

Runtime calls execute under that connection context.

Therefore:

Swagger

≠

Credentials

This distinction becomes critical in enterprise Power Platform architecture.

25. What Is a Power Platform Custom Connector?

Microsoft describes connectors as wrappers around APIs.

A Custom Connector allows us to create such a wrapper for an API that doesn’t already have the connector we need.

Conceptually:

REST API

↓

OpenAPI definition

↓

Custom Connector

↓

Operations

↓

Power Platform

Once created, an API operation can become a reusable capability.

Instead of every application manually building HTTP requests, the connector provides an abstraction.

26. Raw REST vs Custom Connector

Without a connector:

Power Automate

↓

HTTP

↓

URL

↓

Headers

↓

Parameters

↓

JSON

↓

Manual parsing

With a Custom Connector:

Power Automate

↓

GetWeatherForecast

↓

Inputs

↓

Structured outputs

The second model is generally easier to reuse and govern.

27. Creating the Open-Meteo Custom Connector

The Microsoft workflow conceptually becomes:

Power Apps

→ Custom connectors

→ New custom connector

→ Import an OpenAPI file

The Swagger file is imported.

Power Platform reads properties such as:

host

basePath

schemes

paths

parameters

responses

securityDefinitions

and creates a connector definition around them.

Microsoft currently documents that OpenAPI definitions imported for this Custom Connector workflow must use OpenAPI 2.0, historically called Swagger, rather than OpenAPI 3.0.

That requirement explains why Swagger 2.0 remains relevant even though newer OpenAPI specifications exist.

28. The Custom Connector Wizard

The Power Platform Custom Connector experience is broadly divided into areas such as:

General

Security

Definition

Code

Test

The exact interface can evolve, but the conceptual responsibilities remain useful.

General

Defines where the API exists.

Examples:

Host

Base URL

Protocol

Security

Defines authentication.

Examples:

No authentication

API Key

Basic

OAuth 2.0

Definition

Defines operations.

Examples:

GetWeatherForecast

GetHistoricalWeather

Code

Allows additional transformation/custom behavior where supported and necessary.

Test

Allows us to create/use a connection and execute operations.

29. Connection vs Connector

This distinction causes considerable confusion.

Connector

describes HOW to communicate with a service.

Connection

represents a configured runtime connection to that service.

Think about:

Connector = class

Connection = instance

or:

Connector = blueprint

Connection = configured access

For our public Open-Meteo example:

Open-Meteo Custom Connector

↓

Connection

↓

API calls

For authenticated APIs, the Connection becomes even more significant because credentials and identity context are involved.

30. The Complete Power Platform Architecture

Our architecture is now:

Open-Meteo REST API

↓

Swagger 2.0 contract

↓

Power Platform Custom Connector

↓

Connection

↓

Operations

↓

Consumers

The consumers could include:

Power Apps

Power Automate

Copilot Studio

Azure Logic Apps

This reuse is one of the strongest reasons to understand Custom Connectors.

31. Using the Connector in Power Apps

Imagine a simple Power Apps application containing:

Latitude input

Longitude input

Button

Temperature label

The application can call the connector operation.

Conceptually:

User clicks button

↓

Power Apps

↓

OpenMeteo.GetWeatherForecast(…)

↓

Custom Connector

↓

HTTPS GET

↓

Open-Meteo

↓

JSON

↓

Connector response

↓

Power Apps

↓

Display temperature

Power Apps does not need to understand all low-level HTTP mechanics every time.

The connector encapsulates them.

32. Using the Connector in Power Automate

The same operation could participate in a flow.

Example:

Scheduled Flow

↓

Get Weather Forecast

↓

Evaluate precipitation

↓

Condition

↓

Send Teams notification

Again:

Power Automate

↓

Custom Connector

↓

Open-Meteo

The integration contract is reusable.

33. Using the Connector in Copilot Studio

This becomes particularly interesting for our Agents work.

Microsoft Copilot Studio can use Power Platform connectors as Tools.

Conceptually:

User:

“What is the weather in this location?”

↓

Agent

↓

Generative Orchestration

↓

Select Tool

↓

Open-Meteo Custom Connector

↓

GetWeatherForecast

↓

Open-Meteo API

↓

Structured JSON

↓

Tool result

↓

Agent

↓

Natural-language answer

This is fundamentally different from Knowledge.

34. Knowledge vs Tool

This distinction is essential.

A weather forecast should generally not be treated as static Knowledge.

Weather is dynamic.

Knowledge might answer:

“What does our company policy say about severe weather?”

A Tool can answer:

“What is the current temperature?”

Therefore:

This distinction is central to Agent architecture.

35. Swagger as an Agent Contract

Swagger becomes even more interesting in the Agent era.

Traditionally we could think:

Swagger

→ developer documentation

Then:

Swagger

→ API client generation

Then:

Swagger

→ Power Platform Custom Connector

Now we can also think:

Swagger

→ Tool contract

→ Agent capability

The API definition tells the platform:

What operation exists?

What is it called?

What does it do?

What inputs does it require?

What does it return?

This information helps transform an external REST API into something an Agent can use.

36. Descriptions Become More Important with Agents

Suppose our Tool has:

operationId: GetWeatherForecast
summary: Get weather forecast
description: Retrieves current and forecast weather information for a geographical location identified by latitude and longitude.

That description is useful for a developer.

But it is also semantically meaningful for orchestration.

Compare it with:

description: Execute operation.

The second description is technically valid but semantically poor.

For agentic systems, descriptions should clearly explain:

• what the operation does
• when it should be used
• what information it requires
• what it returns
• what it does NOT do

API design and prompt/tool design therefore begin to overlap.

37. Good operationId Design

Avoid vague operation IDs such as:

DoSomething

Execute

Run

Action1

Prefer:

GetCurrentWeather

GetWeatherForecast

GetHistoricalWeather

FindLocationCoordinates

Good naming improves:

Maintainability

Readability

Connector design

Power Automate usage

Power Apps formulas

Agent Tool understanding

38. Open-Meteo and Geographical Coordinates

Our current Open-Meteo operation requires:

latitude

longitude

But users normally don’t talk like APIs.

A human says:

“What’s the weather in Cape Town?”

The API expects:

latitude

longitude

This reveals an important integration problem:

Natural language entity

→ structured API parameters

An Agent could potentially identify or obtain coordinates through another capability.

Conceptually:

User

“What’s the weather in Cape Town?”

↓

Agent

↓

Determine coordinates

↓

GetWeatherForecast(latitude, longitude)

↓

Open-Meteo

This illustrates why Agents can be powerful orchestration layers over traditional APIs.

39. API Composition

Imagine two APIs:

Geocoding API

and

Weather API

The architecture becomes:

User

↓

Agent

↓

GetCoordinates(“Cape Town”)

↓

latitude + longitude

↓

GetWeatherForecast(latitude, longitude)

↓

Weather result

↓

Agent

↓

Natural-language answer

Now we are no longer merely calling an API.

We are composing Tools.

This is where orchestration becomes important.

40. Swagger Does Not Provide Reasoning

Swagger is deterministic metadata.

It says:

Operation exists.

Input X is required.

Output Y has this schema.

It does not decide:

“Should I call this operation?”

That decision belongs to the application, workflow, Topic, or Agent orchestration.

Therefore:

Swagger = capability definition

Agent = reasoning/orchestration layer

API = execution layer

This separation is extremely important.

41. Power Automate vs Copilot Studio

Suppose every morning at 08:00 we want to check the weather.

There is no reason to use generative reasoning just to determine that the API should execute.

Power Automate is appropriate:

Recurrence

↓

Open-Meteo Connector

↓

Condition

↓

Notification

But suppose the requirement is:

A user asks arbitrary questions about weather, locations and forecasts in natural language, and the system must determine which capability to invoke.

Now Copilot Studio becomes much more interesting.

The architectural principle is:

Do not introduce an Agent when deterministic automation is enough.

42. Custom Connector vs Direct REST API Tool

Current Copilot Studio also provides REST API as a Tool mechanism.

This creates two architectural possibilities.

Option A

REST API

↓

Custom Connector

↓

Copilot Studio Tool

Option B

REST API

↓

Copilot Studio REST API Tool

The Custom Connector approach becomes especially interesting when the integration should be reused by:

Power Apps

Power Automate

Copilot Studio

Logic Apps

or other Power Platform workloads.

A direct REST API Tool may be attractive when the integration exists specifically for the Agent and doesn’t require a broader reusable connector abstraction.

This is an architectural decision, not simply a technical one.

43. Why Learn Custom Connectors Anyway?

Even though Copilot Studio can work directly with REST APIs in supported scenarios, Custom Connectors remain extremely valuable.

They teach the complete integration architecture:

API contract

Authentication

Operations

Inputs

Outputs

Connections

Reuse

Governance

Environment lifecycle

Power Platform integration

And the same connector can participate in multiple solutions.

For someone working across SharePoint, Power Automate, Power Apps and Copilot Studio, this is particularly useful.

44. Swagger and Power Platform Extensions

Microsoft adds extensions to OpenAPI definitions for Power Platform scenarios.

Many use the prefix:

x-ms-

These extensions can influence how operations and parameters appear and behave in Microsoft products.

Examples encountered in the broader Power Platform ecosystem include concepts such as:

visibility

dynamic values

dynamic schemas

operation metadata

These extensions allow a generic OpenAPI contract to become more tightly integrated with Power Platform experiences.

This is an advanced topic worth studying after mastering standard Swagger.

45. A Practical Minimal Swagger Example

A learning-oriented Open-Meteo definition could conceptually resemble:

swagger: "2.0"
info:
  title: Open-Meteo Weather
  description: Custom connector for retrieving weather information from Open-Meteo.
  version: "1.0"
host: api.open-meteo.com
basePath: /v1
schemes:
  - https
produces:
  - application/json
paths:
  /forecast:
    get:
      summary: Get weather forecast
      description: Retrieves weather information using geographical coordinates.
      operationId: GetWeatherForecast
      parameters:
        - name: latitude
          in: query
          required: true
          type: number
          format: double
          description: Latitude in WGS84 format.
        - name: longitude
          in: query
          required: true
          type: number
          format: double
          description: Longitude in WGS84 format.
        - name: timezone
          in: query
          required: false
          type: string
          description: Timezone used for returned weather data.
      responses:
        "200":
          description: Successful response
          schema:
            type: object

This is intentionally minimal.

A production-quality definition should model the required request and response structures more carefully.

46. Why Start Small?

When learning Custom Connectors, avoid immediately exposing every endpoint and every Open-Meteo parameter.

Start with:

one API

one endpoint

one method

two or three parameters

one successful response

Then test.

This follows an important integration principle:

Minimize variables while learning or troubleshooting.

Only after the basic operation works should we add:

More parameters

Response schemas

Additional endpoints

Authentication

Advanced OpenAPI extensions

Agent orchestration

47. Testing Strategy

A good integration test sequence is:

REST API directly

↓

Swagger contract

↓

Custom Connector Test

↓

Power Apps or Power Automate

↓

Copilot Studio Tool

This isolates failures.

If the API itself fails, the problem isn’t Copilot Studio.

If the API works but the Custom Connector fails, inspect the Swagger/connector.

If the connector works but the Agent doesn’t call it correctly, investigate Tool descriptions, parameters, Instructions and orchestration.

This layered testing strategy becomes extremely useful in enterprise integrations.

48. Common Errors

Typical Swagger/Connector problems include:

Incorrect host

Wrong:

host: https://api.open-meteo.com

Correct conceptually:

host: api.open-meteo.com

Wrong base path

If the base path and endpoint path overlap, the resulting URL may be incorrect.

Missing required parameter

The API requires latitude but the connector doesn’t supply it.

Wrong parameter type

API expects number while the schema declares string.

Incorrect response schema

The API returns an object but Swagger describes an array.

Authentication mismatch

The connector expects API Key while the API expects OAuth.

Poor operation descriptions

The integration technically works, but an Agent has insufficient semantic information to select the correct Tool reliably.

49. Security

Our Open-Meteo example intentionally has a simple security model.

Enterprise APIs are different.

For every Custom Connector ask:

Who owns the Connector?

Who can use it?

Who can create Connections?

Which credentials does the Connection use?

Which API permissions exist?

Which environment contains the Connector?

Can the Connector be shared?

Can it cross a Power Platform data policy boundary?

What information leaves Microsoft 365?

Where is the external API hosted?

Does the API receive personal or confidential data?

An API integration is also a security boundary.

50. Agent Security Adds Another Layer

With Copilot Studio we must additionally ask:

User

↓

Agent

↓

Tool

↓

Connection

↓

External API

Which identity exists at each point?

Do not assume:

User permissions = Connector permissions.

They can represent different security contexts.

This becomes particularly important when Tools can write or modify data.

51. Read Operations vs Write Operations

Our weather example is intentionally read-oriented.

GET

→ retrieve weather

Later we might integrate an API exposing:

POST /requests

PATCH /requests/{id}

DELETE /requests/{id}

Now the Agent can change external state.

The risk increases significantly.

An incorrect weather query might produce a bad answer.

An incorrectly orchestrated DELETE operation might remove business data.

Therefore Tool design should consider:

least privilege

confirmation

input validation

authentication

authorization

auditing

monitoring

idempotency

error handling

52. Swagger and API Governance

Swagger is not merely a developer convenience.

It can participate in API governance.

A well-designed API contract establishes:

Available operations

Accepted parameters

Data types

Expected responses

Authentication requirements

Version

Descriptions

This makes integrations easier to document, review and maintain.

For enterprise solutions, the Swagger definition should be treated as a version-controlled technical artifact.

53. Versioning

Notice:

info:
  version: "1.0"

API evolution matters.

Imagine that version 2 changes:

parameter names

response structure

authentication

endpoint paths

A connector depending on version 1 might break.

Therefore:

API version

Swagger version

Connector version

Solution version

should be considered separately.

Also remember:

swagger: "2.0"

means:

the OpenAPI specification version

while:

info:
  version: "1.0"

means:

the API definition/application version

They are not the same thing.

54. Swagger 2.0 vs OpenAPI 3.x

This naming causes confusion.

Swagger 2.0 became OpenAPI Specification 2.0.

Later specifications include OpenAPI 3.x.

Conceptually:

Swagger 2.0

↓

OpenAPI Specification project

↓

OpenAPI 3.x

However, newer doesn’t automatically mean that every platform import experience accepts every newer specification.

For the Microsoft Custom Connector import workflow discussed here, Microsoft currently documents OpenAPI 2.0 as the required format.

Always check current Microsoft documentation because platform support can evolve.

55. The Full Architecture

We can now build our complete mental model.

External Service

↓

REST API

↓

HTTP contract

↓

Swagger / OpenAPI

↓

Power Platform Custom Connector

↓

Connection

↓

Operations

↓

Power Apps

or

Power Automate

or

Copilot Studio

For Copilot Studio:

User Prompt

↓

Agent

↓

Instructions

↓

Generative Orchestration

↓

Tool selection

↓

Custom Connector Operation

↓

Connection

↓

REST API

↓

JSON

↓

Structured Tool Result

↓

Agent

↓

Generated Answer

This architecture connects traditional API engineering with modern Agent architecture.

56. Mapping the Concepts

57. Open-Meteo as a Learning API

Open-Meteo is particularly useful for studying this architecture because it lets us concentrate first on:

REST

GET

query parameters

JSON

Swagger

Custom Connector

structured responses

without immediately making authentication the dominant problem.

After mastering this, the same architecture can be repeated with an authenticated API.

Then we add:

API Key

or

OAuth 2.0

or

Microsoft Entra ID

That gives us a controlled learning progression.

58. From Weather API to Enterprise API

Today:

User

↓

Agent

↓

Open-Meteo Tool

↓

Weather API

Tomorrow:

Employee

↓

Corporate Agent

↓

Custom Connector

↓

Internal API

↓

Business System

The underlying integration principles remain remarkably similar.

What changes are:

authentication

authorization

security

governance

data sensitivity

error handling

transactional behavior

monitoring

ALM

59. The Most Important Architectural Lesson

Do not think:

Swagger = API.

Instead:

API = capability

Swagger = contract describing the capability

Custom Connector = Power Platform abstraction around the capability

Connection = configured runtime access

Tool = capability exposed to an Agent

Agent = reasoning/orchestration layer that can decide when to use the capability

This distinction prevents many architectural misunderstandings.

60. Final Mental Model

The complete chain is:

Human requirement

↓

REST API

↓

Swagger 2.0 / OpenAPI contract

↓

Custom Connector

↓

Connection

↓

Power Platform operation

↓

Power Apps / Power Automate / Copilot Studio

And inside Copilot Studio:

User

↓

Natural language

↓

Agent

↓

Instructions

↓

Generative Orchestration

↓

Tool

↓

Custom Connector

↓

Connection

↓

REST API

↓

JSON

↓

Structured result

↓

Agent

↓

Natural-language response

Swagger therefore occupies a fascinating position between two worlds.

On one side:

HTTP

REST

JSON

authentication

API engineering

On the other:

Power Apps

Power Automate

Power Platform

Copilot Studio

Agents

Generative Orchestration

Tools

Swagger/OpenAPI provides the machine-readable contract that allows these worlds to communicate.

Conclusion

Swagger 2.0 may initially appear to be little more than a structured API documentation format.

Within Microsoft Power Platform, however, it has a much more practical role.

An OpenAPI definition can transform a raw REST API into a reusable integration contract that Power Platform understands.

From that contract, a Custom Connector can expose operations to applications, workflows and Agents.

Using Open-Meteo, the progression becomes easy to visualize:

Open-Meteo

↓

REST API

↓

Swagger 2.0

↓

Custom Connector

↓

Connection

↓

Power Apps / Power Automate / Copilot Studio

For traditional Power Platform development, this provides reusable API integration.

For Copilot Studio, it introduces another important transformation:

An API operation can become an Agent Tool.

The Agent doesn’t replace the API.

The Agent doesn’t replace Swagger.

The Agent doesn’t replace the Connector.

Each component has a specific responsibility:

Swagger describes.

Connector integrates.

Connection provides runtime access.

API executes.

Agent orchestrates.

Understanding these boundaries is one of the foundations for designing reliable enterprise Agents rather than simply building conversational demos.

Official References

Microsoft Learn — Create a custom connector from an OpenAPI definition

Microsoft Learn — Create a custom connector for a web API

Microsoft Learn — Use Power Platform connectors as tools in Copilot Studio agents

Microsoft Learn — Add tools to custom agents

Open-Meteo — Weather Forecast API Documentation

Quick Reference

The shortest possible mental model is:

REST API = Service

Swagger = Contract

Custom Connector = Adapter

Connection = Access

Tool = Capability

Agent = Orchestrator