At the moment, one of the biggest barriers to adopting ScanAPI is that users need to manually write the API specification. This step has often been the main reason why ScanAPI has not been more widely adopted, as it adds friction to getting started.
Ideally, we would like to move closer to a “plug and play” experience, where the entry barrier is lower and the developer experience is smoother.
Problem
- Today, people must write the ScanAPI specification by hand.
- This requires time, knowledge, and discipline, which discourages adoption.
- We want to explore ways to automate or simplify this process without losing flexibility.
Constraints to keep in mind
- It must work with APIs written in any language.
- It should also work for APIs where we don’t have access to the source code.
- It should still be possible to write tests using Python code, otherwise we lose one of the key purposes of ScanAPI.
- We need to balance effort vs value, developer experience, ease of maintenance, and broad applicability.
Possible Directions
Over the years, several ideas have already been suggested and discussed by the community. Here’s a consolidated list with a brief description of each, plus their potential pros and cons:
| Approach |
Description |
Pros |
Cons |
| Converters (OpenAPI, Postman, Insomnia ↔ ScanAPI spec) |
Build tools to import/export existing API specs into ScanAPI format. |
- Leverages existing standards
- Makes migration easier
- Low barrier for new users |
- Specs can be large/complex
- Needs continuous sync with evolving formats
- May not cover all edge cases
- We still need to define how developers would write automated tests in Python after the conversion |
Framework-specific extensions (e.g. django-scanapi) |
Plugins for specific frameworks that auto-generate ScanAPI specs from code. |
- Seamless integration for specific stacks
- Can generate specs automatically from code |
- Limited to APIs where we control the source
- Harder to maintain across multiple frameworks/languages
- Narrow adoption benefit |
| API discovery script |
A script that probes endpoints automatically and builds a spec. |
- Could work without code access
- Helps explore undocumented APIs
- “Magical” experience for users |
- Risk of incomplete/inaccurate discovery
- Could be slow or noisy
- Hard to maintain, requires heuristics |
| AI-assisted spec generation |
Use AI to generate ScanAPI specs based on docs or observed traffic. |
- Fast and user-friendly
- Works with existing docs or traffic
- Can reduce manual effort significantly |
- Quality depends on input data
- Requires integration with external services
- Might be inconsistent, not always reproducible |
| Spec Builder GUI (visual editor) |
A Postman-like editor where users build endpoints/tests visually, exporting to YAML. |
- Lowers entry barrier for non-YAML users
- Provides a friendly, Postman-like interface
- Can export ready-to-use ScanAPI specs |
- Requires building and maintaining a separate UI
- Adds complexity to the project scope
- May overlap with existing tools instead of being unique |
Next Steps
- Please share other possible suggestions if you have them.
- Let’s refine the pros and cons of each approach.
- The solution may not be a single path — it could be a combination of strategies.
- Still, it would be important to define a clear strategy so we can align expectations and plan implementation accordingly.
I personally believe this is the single biggest limitation of ScanAPI today, and solving it could significantly increase adoption.
Looking forward to hearing your thoughts and ideas! 🙌
At the moment, one of the biggest barriers to adopting ScanAPI is that users need to manually write the API specification. This step has often been the main reason why ScanAPI has not been more widely adopted, as it adds friction to getting started.
Ideally, we would like to move closer to a “plug and play” experience, where the entry barrier is lower and the developer experience is smoother.
Problem
Constraints to keep in mind
Possible Directions
Over the years, several ideas have already been suggested and discussed by the community. Here’s a consolidated list with a brief description of each, plus their potential pros and cons:
- Makes migration easier
- Low barrier for new users
- Needs continuous sync with evolving formats
- May not cover all edge cases
- We still need to define how developers would write automated tests in Python after the conversion
django-scanapi)- Can generate specs automatically from code
- Harder to maintain across multiple frameworks/languages
- Narrow adoption benefit
- Helps explore undocumented APIs
- “Magical” experience for users
- Could be slow or noisy
- Hard to maintain, requires heuristics
- Works with existing docs or traffic
- Can reduce manual effort significantly
- Requires integration with external services
- Might be inconsistent, not always reproducible
- Provides a friendly, Postman-like interface
- Can export ready-to-use ScanAPI specs
- Adds complexity to the project scope
- May overlap with existing tools instead of being unique
Next Steps
I personally believe this is the single biggest limitation of ScanAPI today, and solving it could significantly increase adoption.
Looking forward to hearing your thoughts and ideas! 🙌