# Swagger Petstore Walkthrough
Step-by-step tutorial for trying `pi-openapi-tools` against the public Swagger Petstore examples.
Links in this guide were verified on May 12, 2026:
- Swagger UI:
- Swagger 2.0 spec:
- OpenAPI 3.0 spec:
This is the easiest zero-setup demo for the extension because:
- the specs are public
- the URLs are stable
- the API has both `apiKey` and OAuth security metadata
- the v2 and v3 specs exercise different parsing paths in this repo
It is also important to know the limitation up front:
- Swagger Petstore is great for security parsing
- Swagger Petstore is not a great end-to-end test for `/swagger-tools:auth`
- the OAuth setup in Petstore is demo-oriented and browser-based, not a real `POST /token` flow
## Prerequisites
Make sure the extension is installed and loaded in Pi.
```bash
pi install npm:pi-openapi-tools
```
If you are running from source, start Pi with this extension:
```bash
pi -e /path/to/pi-openapi-tools/extensions/index.ts
```
## Step 1: Inspect the Petstore UI first
Open the public Swagger UI:
-
This gives you a quick feel for the API before generating tools. In the UI, look for:
- the `Authorize` button
- the `pet`, `store`, and `user` groups
- read-only endpoints such as `GET /store/order/{orderId}` and `GET /user/login`
- secured endpoints such as `GET /pet/{petId}` and `GET /store/inventory`
For the demo API key flow, the Swagger 2.0 spec explicitly says you can use:
```text
special-key
```
Use the UI mainly as a reference for endpoint names and auth behavior. The actual tool generation happens from the raw JSON specs below.
## Step 2: Generate tools from the Swagger 2.0 spec
Run:
```text
/swagger-tools https://petstore.swagger.io/v2/swagger.json --prefix petv2
```
Why this is useful:
- it exercises the Swagger 2.0 code path in this repo
- base URL inference comes from `host`, `basePath`, and `schemes`
- auth metadata comes from `securityDefinitions`
- request bodies use Swagger 2.0 `body` and `formData` parameters
Now list what was generated:
```text
/swagger-tools:list
```
You should see tool names based on `operationId`, for example:
- `petv2_findpetsbystatus`
- `petv2_getpetbyid`
- `petv2_getinventory`
- `petv2_deletepet`
- `petv2_loginuser`
## Step 3: Try Swagger 2.0 execution calls (GET + POST)
Start with low-friction calls that validate path/query/body mapping.
### 3a) Read-only order lookup (`GET`)
Example tool:
```text
petv2_getorderbyid
```
Example arguments:
```json
{
"path": {
"orderId": 1
}
}
```
### 3b) Query-string login (`GET`)
Example tool:
```text
petv2_loginuser
```
Example arguments:
```json
{
"query": {
"username": "user1",
"password": "string"
}
}
```
### 3c) JSON body user creation (`POST`)
Example tool:
```text
petv2_createuser
```
Example arguments:
```json
{
"body": {
"username": "user1",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane@example.com"
}
}
```
These three calls confirm that:
- the spec fetched correctly
- the inferred base URL is correct
- path, query, and body parameters are mapped as expected
- JSON request serialization works for Swagger 2.0 `in: body` parameters
## Step 4: Inspect how Swagger 2.0 auth shows up
Describe a few tools:
```text
/swagger-tools:describe petv2_getpetbyid
/swagger-tools:describe petv2_getinventory
/swagger-tools:describe petv2_deletepet
```
This is where Petstore becomes a good parsing example.
What to notice:
- `getPetById` and `getInventory` are marked as secured in the spec
- `deletePet` includes an explicit header parameter named `api_key`
- the extension shows declared parameters in the generated schema
Important nuance for this repo:
- current stored auth is injected as an `Authorization` header
- Petstore's API key scheme uses an `api_key` header
- security metadata is useful for inspection, but it does not automatically become a full non-`Authorization` auth workflow
Because `deletePet` mutates shared demo data, use `describe` for inspection and be deliberate before actually calling it.
## Step 5: Try the Petstore auth demo in Swagger UI
Back in the UI, click `Authorize`.
You can use it to see both auth styles:
- `api_key`: enter `special-key`
- `petstore_auth`: follow the demo OAuth prompt and choose scopes such as `read:pets` and `write:pets`
This is helpful for understanding the spec, but treat it as a UI demo rather than a production OAuth example.
## Step 6: Generate tools from the OpenAPI 3.0 spec
Run:
```text
/swagger-tools https://petstore3.swagger.io/api/v3/openapi.json --prefix petv3
```
Why this is useful:
- it exercises the OpenAPI 3.x code path
- base URL inference comes from `servers[0].url`
- the Petstore v3 spec uses a relative server URL, so the extension resolves it against the spec URL
- auth metadata comes from `components.securitySchemes`
- request bodies use `requestBody` instead of Swagger 2.0 `body` or `formData`
List the tools again:
```text
/swagger-tools:list
```
You should now have a second prefix alongside the v2 tools, for example:
- `petv3_addpet`
- `petv3_findpetsbystatus`
- `petv3_getorderbyid`
- `petv3_uploadfile`
- `petv3_loginuser`
## Step 7: Compare OpenAPI 3.0 execution calls (GET + POST)
### 7a) Read-only order lookup (`GET`)
```text
petv3_getorderbyid
```
Example arguments:
```json
{
"path": {
"orderId": 1
}
}
```
### 7b) User creation (`POST` with requestBody)
```text
petv3_createuser
```
Example arguments:
```json
{
"body": {
"username": "user2",
"firstName": "John",
"lastName": "Smith",
"email": "john@example.com"
}
}
```
### 7c) Pet creation (`POST` with requestBody)
```text
petv3_addpet
```
Example arguments:
```json
{
"body": {
"name": "Fluffy",
"status": "available"
}
}
```
Then inspect the richer body schemas:
```text
/swagger-tools:describe petv3_createuser
/swagger-tools:describe petv3_addpet
```
This confirms OpenAPI 3.0 `requestBody` parsing and JSON serialization.
## Step 8: Understand why `/swagger-tools:auth` is weak here
This repo's auth helper looks for a `POST` endpoint whose path or description includes one of:
- `token`
- `oauth`
- `openid`
- `oidc`
Swagger Petstore does not expose a real token endpoint in its `paths`.
Instead, the security metadata points to browser authorization pages:
- Swagger 2.0: `securityDefinitions.petstore_auth.authorizationUrl = https://petstore.swagger.io/oauth/authorize`
- OpenAPI 3.0: `components.securitySchemes.petstore_auth.flows.implicit.authorizationUrl = https://petstore3.swagger.io/oauth/authorize`
So Petstore is useful for:
- verifying that the extension can parse OAuth metadata
- checking how secured operations are represented
- manually exploring auth in Swagger UI
Petstore is not useful for:
- validating automatic token discovery
- validating a client credentials flow
- validating a real `access_token` response from a generated token tool
If you want to test `/swagger-tools:auth` itself, use a spec that actually includes a `POST /token` or `POST /oauth/token` operation.
## Step 9: Clean up generated prefixes
When you are done:
```text
/swagger-tools:remove-prefix petv2
/swagger-tools:remove-prefix petv3
/swagger-tools:list-prefixes
```
You should see:
```text
No Swagger tools registered yet.
```
## What Petstore is best for
- zero-setup smoke tests
- comparing Swagger 2.0 and OpenAPI 3.0 behavior
- checking tool naming from `operationId`
- validating path, query, body, and file-shape parsing
- inspecting `apiKey` and OAuth security metadata
## Automated test that simulates this tutorial
This repo includes an integration-style test that mirrors this walkthrough:
- `tests/swagger-petstore-tutorial.test.ts`
Run it with Bun:
```bash
bun test tests/swagger-petstore-tutorial.test.ts
```
The test logs a full call trace (spec fetches + endpoint calls), including method, URL, headers, and JSON request bodies for POST calls.
Expected high-level trace shape:
1. Fetch v2 spec (`GET .../v2/swagger.json`)
2. v2 order lookup (`GET /v2/store/order/1`)
3. v2 login (`GET /v2/user/login?...`)
4. v2 create user (`POST /v2/user`)
5. Fetch v3 spec (`GET .../api/v3/openapi.json`)
6. v3 order lookup (`GET /api/v3/store/order/1`)
7. v3 create user (`POST /api/v3/user`)
8. v3 add pet (`POST /api/v3/pet`)
## What to use next
After Petstore, move on to a spec with a real token endpoint if you want to test stored auth end to end. Good candidates are APIs that expose a documented `POST /oauth/token` or similar operation directly in the OpenAPI document.