feat: implements openapi to scanapi.yaml convertion by guites · Pull Request #866 · scanapi/scanapi

guites · 2026-03-04T01:33:48Z

Description

Implements a OpenAPI specification to ScanAPI.yaml convertion.

Motivation behind this PR?

Increasing ScanAPI adoption by reducing friction is a long going issue (see #814).

This PR attempts to provide a sample script that converts OpenAPI v3 files, which are very popular, into a scanapi.yaml file.

The objective is to give project maintainers a starting point into implementation ScanAPI to their pipelines.

I'm referring to this starting scanapi.yaml file as a skeleton file. The skeleton should include (by running the convertion script once):

One request for each existing endpoint listed on the OpenAPI spec.
Each request should have a simple test that checks whether the expected HTTP status for that endpoint is being returned.
Each request (that expects a path variable in the URL) should have the URL pre populated with a custom variable.
Each request (that expects an HTTP body) should have the body pre populated with custom variables.
Each request (that expects authentication) should have the "headers" section pre populated with custom variables.

Benefits to this approach:

An adopting project can quickly set up a custom scanapi.yaml file;
The adopting project immediately benefits by receiving a set of automated "sanity tests" (with minimal tinkering)

Some downsides:

After running the convertion script, the project maintainer will be expected to fill missing information such as creating custom variables and/or environment variables. I don't think this is a huge issue because it's less work than starting from scratch
After generating the skeleton file, any changes to it would be lost if the convertion script is ran again. This could be prevented by implementing a "sync" mechanism, where additions or removals from the OpenAPI spec file are reflected on the scanapi.yaml file. I think this is out of the scope of the current implementation.
This adds a few dependencies (namely, two) to our project: prance (https://github.com/RonnyPfannschmidt/prance) and openapi-spec-validator (https://github.com/python-openapi/openapi-spec-validator).

Example usage

Let's take the Futurama API project as an example. It's swagger documentation can be accessed here: https://futuramaapi.com/swagger#/ .

We can download the OpenAPI spec file (from https://futuramaapi.com/openapi.json) and run the following command:

$ uv run scanapi convert openapi.json -o scanapi-futurama.yaml -b https://futuramaapi.com
OpenAPI/Swagger version detected: 3.1.0

The following variables were created in the generated ScanAPI YAML file:
- ${Create_User_surname}
- ${Character_Sse_character_id}
- ${Get_Link_link_id}
- ${Create_User_username}
- ${Create_Favorite_Character_character_id}
- ${Create_User_name}
- ${Create_User_password}
- ${Get_User_Auth_Token_username}
- ${Episode_Callback_episode_id}
- ${Character_Callback_callbackUrl}
- ${Get_User_Auth_Token_password}
- ${Create_User_email}
- ${Get_Secret_Message_url}
- ${bearer_token}
- ${Create_Secret_Message_text}
- ${Character_Callback_character_id}
- ${Season_Callback_callbackUrl}
- ${Episode_episode_id}
- ${Character_character_id}
- ${Delete_Favorite_Character_character_id}
- ${Request_Change_User_Password_email}
- ${Season_season_id}
- ${Create_Link_url}
- ${Season_Callback_season_id}
- ${Episode_Callback_callbackUrl}
- ${Get_Refreshed_User_Auth_Token_refresh_token}
See https://scanapi.dev/docs_v1/specification/custom_variables and https://scanapi.dev/docs_v1/specification/environment_variables for more information.

File successfully converted and exported as "scanapi-futurama.yaml"!

This would result in the following ScanAPI yaml:

$ cat scanapi-futurama.yaml

endpoints:
-   name: FastAPI
    path:  https://futuramaapi.com
    requests:
    -   name: Character_Callback
        path: /api/callbacks/characters/${Character_Callback_character_id}
        method: post
        tests:
        -   name: status_code_is_201
            assert: ${{response.status_code == 201}}
        body:
            callbackUrl: ${Character_Callback_callbackUrl}
    -   name: Episode_Callback
        path: /api/callbacks/episodes/${Episode_Callback_episode_id}
        method: post
        tests:
        -   name: status_code_is_201
            assert: ${{response.status_code == 201}}
        body:
            callbackUrl: ${Episode_Callback_callbackUrl}
    -   name: Season_Callback
        path: /api/callbacks/seasons/${Season_Callback_season_id}
        method: post
        tests:
        -   name: status_code_is_201
            assert: ${{response.status_code == 201}}
        body:
            callbackUrl: ${Season_Callback_callbackUrl}
    -   name: Random_Character
        path: /api/random/character
        method: get
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
    -   name: Random_Episode
        path: /api/random/episode
        method: get
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
    -   name: Random_Season
        path: /api/random/season
        method: get
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
    -   name: Character
        path: /api/characters/${Character_character_id}
        method: get
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
    -   name: Characters
        path: /api/characters
        method: get
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
    -   name: Create_Secret_Message
        path: /api/crypto/secret_message
        method: post
        tests:
        -   name: status_code_is_201
            assert: ${{response.status_code == 201}}
        body:
            text: ${Create_Secret_Message_text}
    -   name: Get_Secret_Message
        path: /api/crypto/secret_message/${Get_Secret_Message_url}
        method: get
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
    -   name: Episode
        path: /api/episodes/${Episode_episode_id}
        method: get
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
    -   name: Episodes
        path: /api/episodes
        method: get
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
    -   name: Character_Sse
        path: /api/notifications/sse/characters/${Character_Sse_character_id}
        method: get
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
    -   name: Season
        path: /api/seasons/${Season_season_id}
        method: get
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
    -   name: Seasons
        path: /api/seasons
        method: get
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
    -   name: Get_User_Auth_Token
        path: /api/tokens/users/auth
        method: post
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
        body:
            username: ${Get_User_Auth_Token_username}
            password: ${Get_User_Auth_Token_password}
    -   name: Get_Refreshed_User_Auth_Token
        path: /api/tokens/users/refresh
        method: post
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
        body:
            refresh_token: ${Get_Refreshed_User_Auth_Token_refresh_token}
    -   name: Create_User
        path: /api/users
        method: post
        tests:
        -   name: status_code_is_201
            assert: ${{response.status_code == 201}}
        body:
            name: ${Create_User_name}
            surname: ${Create_User_surname}
            email: ${Create_User_email}
            username: ${Create_User_username}
            password: ${Create_User_password}
    -   name: List_Users
        path: /api/users
        method: get
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
    -   name: Update_User
        path: /api/users
        method: put
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
        headers:
            Authorization: Bearer ${bearer_token}
    -   name: User_Me
        path: /api/users/me
        method: get
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
        headers:
            Authorization: Bearer ${bearer_token}
    -   name: Resend_User_Confirmation
        path: /api/users/confirmations/resend
        method: post
        tests:
        -   name: status_code_is_202
            assert: ${{response.status_code == 202}}
        headers:
            Authorization: Bearer ${bearer_token}
    -   name: Request_Change_User_Password
        path: /api/users/passwords/request-change
        method: post
        tests:
        -   name: status_code_is_202
            assert: ${{response.status_code == 202}}
        body:
            email: ${Request_Change_User_Password_email}
    -   name: Create_Link
        path: /api/links
        method: post
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
        body:
            url: ${Create_Link_url}
        headers:
            Authorization: Bearer ${bearer_token}
    -   name: List_Links
        path: /api/links
        method: get
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
        headers:
            Authorization: Bearer ${bearer_token}
    -   name: Get_Link
        path: /api/links/${Get_Link_link_id}
        method: get
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
        headers:
            Authorization: Bearer ${bearer_token}
    -   name: Create_Favorite_Character
        path: /api/favorites/characters/${Create_Favorite_Character_character_id}
        method: post
        tests:
        -   name: status_code_is_204
            assert: ${{response.status_code == 204}}
        headers:
            Authorization: Bearer ${bearer_token}
    -   name: Delete_Favorite_Character
        path: /api/favorites/characters/${Delete_Favorite_Character_character_id}
        method: delete
        tests:
        -   name: status_code_is_204
            assert: ${{response.status_code == 204}}
        headers:
            Authorization: Bearer ${bearer_token}
    -   name: List_Favorite_Characters
        path: /api/favorites/characters
        method: get
        tests:
        -   name: status_code_is_200
            assert: ${{response.status_code == 200}}
        headers:
            Authorization: Bearer ${bearer_token}

Points of interest:

Endpoints that require authentication have a headers entry with Authorization: Bearer ${bearer_token}. If we defined the bearer_token anywhere on the file, we have working authentication for these endpoints.
Endpoints with path parameters (such as /api/characters/${Character_character_id}) have the path parameter as a variable. This means we can quickly implement this variable in another endpoint.
Endpoints with a body have that body pre filled with variables.

What type of change is this?

Implementation of a new feature.

Checklist

A changelog entry was added, or this PR does not require one. Instructions
Unit tests were added or updated as needed, or not required for this change. Instructions
All unit tests pass locally. Instructions
Docstrings or comments were added or updated as needed, or no documentation changes were required. Instructions
This PR does not significantly reduce code or docstring coverage.
Code follows the project’s style guidelines.
ScanAPI was run locally and the changes were manually verified, or this was not necessary. Instructions

Issue

Closes #866

this could happen if the same path has multiple methods without summary/operationId

guites · 2026-03-04T21:29:07Z

Hey :) I think the code reached its final form. I'm marking it as ready for commit, but I'll still add tests for the convert method, which should bump coverage back to 98%!

feat: convert openapi spec

guites · 2026-04-12T20:52:27Z

I've fixed most of deepsource problems and ignored all documentation/formatting related issues (see https://app.deepsource.com/gh/scanapi/scanapi/run/0ae4f501-371d-478b-b552-235b85f2473f/python/). I think we can go ahead and skip deepsource output altogether for this PR.

guites · 2026-04-12T21:20:50Z

Our convertion pipeline is based on prance (https://github.com/RonnyPfannschmidt/prance) using the openapi-spec-validator backend (https://github.com/p1c2u/openapi-spec-validator).

The default behavior is to block parsing of schemas with non-compliant fields.

For example the following schema (the "example" field is defined incorrectly under a response definition. see https://spec.openapis.org/oas/v3.1.0#response-object) :

openapi: 3.0.4
info:
  title: Sample API
  version: 0.1.9

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        "200":
          description: A JSON array of user names
          example: "teste"
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

Would result in the following error (when running uv run scanapi from example.yaml):

ERROR Couldn't parse OpenAPI schema: ("{'description': 'A JSON array of user names', 'example': 'teste', 'content': {'application/json': {'schema': {'type': 'array', 'items': {'type': 'string'}}}}} is
not valid under any of the given schemas", 'oneOf', deque(['paths', '/users', 'get', 'responses', '200']), None, [<ValidationError: "'example' does not match any of the regexes: '^x-'">,
<ValidationError: "'$ref' is a required property">], [{'$ref': '#/definitions/Response'}, {'$ref': '#/definitions/Reference'}], {'description': 'A JSON array of user names', 'example': 'teste',
'content': {'application/json': {'schema': {'type': 'array', 'items': {'type': 'string'}}}}}, {'oneOf': [{'$ref': '#/definitions/Response'}, {'$ref': '#/definitions/Reference'}]},
deque(['properties', 'paths', 'patternProperties', '^\/', 'patternProperties', '^(get|put|post|delete|options|head|patch|trace)$', 'properties', 'responses', 'patternProperties',
'^1-5$', 'oneOf']), None)

The specific error (in this case <ValidationError: "'example' does not match any of the regexes: '^x-'">, <ValidationError: "'$ref' is a required property">) depends on the OpenAPI version.

If we change version 3.0.4 to 3.1.0, keeping the same schema, we get the following error:

ERROR Couldn't parse OpenAPI schema: ("Unevaluated properties are not allowed ('example' was unexpected)", 'unevaluatedProperties', deque(['paths', '/users', 'get', 'responses', '200']), None, [],
False, {'description': 'A JSON array of user names', 'example': 'teste', 'content': {'application/json': {'schema': {'type': 'array', 'items': {'type': 'string'}}}}}, {'$comment':
'https://spec.openapis.org/oas/v3.1.0#response-object', 'type': 'object', 'properties': {'description': {'type': 'string'}, 'headers': {'type': 'object', 'additionalProperties': {'$ref':
'#/$defs/header-or-reference'}}, 'content': {'$ref': '#/$defs/content'}, 'links': {'type': 'object', 'additionalProperties': {'$ref': '#/$defs/link-or-reference'}}}, 'required': ['description'],
'$ref': '#/$defs/specification-extensions', 'unevaluatedProperties': False}, deque(['properties', 'paths', 'patternProperties', '^/', 'else', 'properties', 'get', 'properties', 'responses',
'patternProperties', '^1-5$', 'else', 'unevaluatedProperties']), None)

The error changed to "Unevaluated properties are not allowed ('example' was unexpected)".

I think it's pretty common for OpenAPI specs to have incorrect/incompatible fields, since there are so many spec generation tools out there.

cc @camilamaia wdyt? Should we move forward with a "strict" implementation for now and study having a --lax option later on, or do you think this is a blocker?

prance seems to accept a Strict flag (see https://github.com/RonnyPfannschmidt/prance/blob/main/prance/__init__.py#L128) but it still isn't clear how it works or how we could send this flag over.

edit: the strict flag on prance works by stringifying integer keys, so it's unrelated to our non-default keys problem

camilamaia · 2026-04-21T15:31:29Z

Great point, @guites. Some thoughts that might help move it forward:

Would it make sense to replace the inline TODOs with GitHub issues?
That keeps the codebase cleaner, avoids static analysis complaints (e.g. DeepSource), and also creates a clearer backlog of follow-up improvements.
I think keeping validation strict for this first version is a reasonable tradeoff, since it reduces complexity and keeps behavior predictable.
That said, it may help to improve the current error message a bit so users understand what is required, instead of only surfacing the upstream parser/validator exception.

For example, something like:

Invalid OpenAPI schema.
Conversion currently requires a valid OpenAPI 3.x document.
Details: <validator error>

Since you already mentioned the idea of a more flexible validation mode, would it make sense to open a follow-up issue for that?
I think that would be a good place to discuss options such as lax / best-effort parsing for partially invalid specs that are still usable for skeleton generation, while keeping this PR focused on the strict first version.

Overall, I’d be in favor of keeping the current implementation strict for now and tracking the flexibility improvements separately.

guites · 2026-04-24T13:46:29Z

@camilamaia I agree with all points :) Will try to do the changes asap.

Create the issues from the TODOs: Handle falsy values when getting endpoint parameter names #901, Handle query parameters in OpenAPI spec convertion #902, Handle full oauth2 authentication flow #903
Try to wrap the error message in a more friendly message;
Open up an issue to advance the discussion regarding the lax mode: Parse invalid/incomplete OpenAPI specs #904

The error message now reads

ERROR Invalid OpenAPI schema.
Conversion currently requires a valid OpenAPI 3.x document.
Details: ("'' does not match '[^/#?]+$'", 'pattern', deque(['paths', '/api/characters/{}', 'get', 'parameters', 0, 'name']), None, [], '[^/#?]+$', '', {'pattern': '[^/#?]+$'},
deque(['properties', 'paths', 'patternProperties', '^/', 'else', 'properties', 'get', 'properties', 'parameters', 'items', 'else', 'dependentSchemas', 'schema', 'allOf', 1, 'then', 'properties',
'name', 'pattern']), None)

Co-authored-by: Camila Maia <[email protected]>

guites · 2026-04-24T20:38:26Z

cc @camilamaia I think I made all mentioned changes :) lmk if anything else comes up

guites · 2026-04-24T20:42:44Z

deepsource seems to be pleased

github-actions

Thank you for supporting ScanAPI, and congratulations on your first contribution! A project committer will shortly review your contribution.

In the mean time, if you haven't had a chance please skim over the First Pull Request Guide which all pull requests must adhere to.

We hope to see you around!

camilamaia

YAY!!!!!!

feat: implements openapi to scanapi.yaml convertion

8156ca9

guites mentioned this pull request Mar 4, 2026

feat: generate ScanAPI spec from OpenAPI #862

Closed

7 tasks

guites added 21 commits March 3, 2026 22:47

fix: adjust required property method return value

0702cbe

fix: handle range definitions when creating response code tests

c945be2

fix: restrict convertion methods to method handled by scanapi

d843fef

fix: handle possible KeyError on security scheme dict

d2b73d1

refactor: define body content type in class variable

19ce2bf

refactor: avoid using python builtin property as var name

a7d4c50

fix: missing call to version validation

93df769

fix: handle missing paths key on spec

88f8152

feat: prevent duplicate target names using method

9ac40f9

this could happen if the same path has multiple methods without summary/operationId

test: unit test the _add_variables_to_path method

6a09879

test: unit test the _get_api_name method

ec296c6

test: unit test the get_api_target_name function

fd98888

docs: adds description to the get_api_target_name function

091f92f

chore: lint test files

55dedd5

fix: handle params with missing name and in keys

3822442

test: unit test the get_required_params function

ac79225

test: unit test the _get_required_properties_from_schema method

b98ee96

test: unit test the _get_security_schemes method

2a1f066

test: unit test the _get_spec_version method

1cf3b04

docs: document the get_tests function

8fa564e

test: unit test the get_tests function

2817108

guites marked this pull request as ready for review March 4, 2026 21:28

guites requested review from a team as code owners March 4, 2026 21:28

guites added 3 commits March 5, 2026 08:24

test: unit test the converter initialization

0ea3e06

test: unit test the _validate_openapi_spec_version method

e3004f8

test: unit test the convert method

453a4d8

camilamaia added 2 commits April 10, 2026 23:31

refactor: create converters module

356a57d

build: update cli with from command

a67e3b1

guites mentioned this pull request Apr 11, 2026

Scanapi spec from openapi guites/scanapi#1

Closed

camilamaia and others added 4 commits April 11, 2026 23:58

docs: add changelog entry

be6763b

Merge pull request #2 from camilamaia/feat/convert-openapi-spec

3e6dc40

feat: convert openapi spec

Merge branch 'main' into feat/convert-openapi-spec

fc2af5d

refactor: suppress unused details variable

4afc337

camilamaia reviewed Apr 21, 2026

View reviewed changes

Comment thread tests/data/convert/invalid.json

Comment thread scanapi/convert.py

guites and others added 5 commits April 24, 2026 16:38

fix: imports sort order

d5e4f1e

Co-authored-by: Camila Maia <[email protected]>

fix: invalid json should have invalid content

b9f928d

docs: move TODO into issue scanapi#901

12895a3

docs: move TODO into issue scanapi#902

efc9eda

docs: move TODO into issue scanapi#903

caf4b9e

guites mentioned this pull request Apr 24, 2026

Parse invalid/incomplete OpenAPI specs #904

Open

fix: improve openapi parsing error message

37a07b4

guites added 2 commits April 24, 2026 17:39

fix: break error msg into multiple lines

e92ecbc

fix: line length fix for deepsource

1237998

github-actions Bot reviewed Apr 27, 2026

View reviewed changes

github-actions Bot added the First Contribution First contribution to the project. label Apr 27, 2026

camilamaia self-requested a review May 8, 2026 12:47

camilamaia approved these changes May 8, 2026

View reviewed changes

camilamaia merged commit 218b232 into scanapi:main May 8, 2026
9 checks passed

dinalivia mentioned this pull request May 11, 2026

chore: Release v2.13.0 #914

Merged

guites mentioned this pull request May 12, 2026

OpenAPI Support for ScanAPI #807

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: implements openapi to scanapi.yaml convertion#866

feat: implements openapi to scanapi.yaml convertion#866
camilamaia merged 46 commits into
scanapi:mainfrom
guites:feat/convert-openapi-spec

guites commented Mar 4, 2026 •

edited by Pradhvan

Loading

Uh oh!

guites commented Mar 4, 2026

Uh oh!

guites commented Apr 12, 2026

Uh oh!

guites commented Apr 12, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

camilamaia commented Apr 21, 2026

Uh oh!

guites commented Apr 24, 2026 •

edited

Loading

Uh oh!

guites commented Apr 24, 2026

Uh oh!

guites commented Apr 24, 2026

Uh oh!

github-actions Bot left a comment

Uh oh!

camilamaia left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

guites commented Mar 4, 2026 • edited by Pradhvan Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation behind this PR?

Example usage

What type of change is this?

Checklist

Issue

Uh oh!

guites commented Mar 4, 2026

Uh oh!

guites commented Apr 12, 2026

Uh oh!

guites commented Apr 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

camilamaia commented Apr 21, 2026

Uh oh!

guites commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

guites commented Apr 24, 2026

Uh oh!

guites commented Apr 24, 2026

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

camilamaia left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

guites commented Mar 4, 2026 •

edited by Pradhvan

Loading

guites commented Apr 12, 2026 •

edited

Loading

guites commented Apr 24, 2026 •

edited

Loading