This example demonstrates how to use Graph-sitter to automatically add OpenAPI decorators (@response and @expect) to Flask-RESTx API endpoints. The migration script analyzes existing code patterns and adds appropriate decorators to improve API documentation.

The script automates the documentation process in several key steps:

1. Resource Class Detection

   for cls in codebase.classes:
       if cls.is_subclass_of("Resource"):
           # Process Flask-RESTx resource classes

   • Identifies Flask-RESTx resource classes
   • Analyzes HTTP method handlers (get, post, put, patch, delete)
   • Determines which decorators are missing

2. Response Analysis

   response_schemas = analyze_method_returns(method)

   • Analyzes return statements
   • Extracts response codes and schemas
   • Handles error responses from http_error calls
   • Processes existing @doc decorators

3. Parameter Analysis

   expect_schema = analyze_method_params(method)

   • Analyzes request parameter usage
   • Detects JSON request body schemas
   • Processes existing @expect decorators

1. Automated Analysis

   • Automatically detects API patterns
   • Infers response and request schemas
   • No manual documentation required

2. Consistent Documentation

   • Ensures all endpoints are documented
   • Maintains consistent decorator usage
   • Preserves existing decorators

3. Intelligent Schema Detection

   • Analyzes model fields
   • Detects request parameter types
   • Handles nested objects

# Before
@ns.route("/endpoint")
class MyResource(Resource):
    def get(self):
        return {"data": result}


# After
@ns.route("/endpoint")
class MyResource(Resource):
    @ns.response(200, "Success", {"data": {"type": "any"}})
    def get(self):
        return {"data": result}

# Before
@ns.route("/endpoint")
class MyResource(Resource):
    def post(self):
        data = request.json["name"]
        return {"status": "success"}


# After
@ns.route("/endpoint")
class MyResource(Resource):
    @ns.expect({"name": {"type": "any", "required": True}})
    @ns.response(200, "Success", {"status": {"type": "any"}})
    def post(self):
        data = request.json["name"]
        return {"status": "success"}

1. Better API Documentation

   • Clear response schemas
   • Documented request parameters
   • Improved API explorer experience

2. Consistent Error Handling

   • Documented error responses
   • Clear status codes
   • Better client integration

3. Time Savings

   • Automated decorator generation
   • Reduced manual documentation work
   • Easier maintenance

# Install Graph-sitter
pip install graph-sitter

# Run the migration
python run.py

The script will:

1. Initialize the codebase
2. Find Flask-RESTx resource classes
3. Analyze methods and add decorators
4. Print detailed analytics about missing decorators

• Flask-RESTx Documentation
• OpenAPI Specification
• Graph-sitter Documentation

Feel free to submit issues and enhancement requests!