A RESTful API to generate portfolio-ready screenshots of your awesome web projects
Note
ALL CONTENTS IN THIS REPO ARE FOR EDUCATIONAL PURPOSES ONLY.
- Description
- Target Users
- Features
- Project Structure
- Quick Start
- Local Setup
- Usage
- Production Setup
- System Administration
- Author(s)
- Version History
- Future Work
- License
- Contributing
- Acknowledgments
- Screenshots
Once a web project is done, it's time to document your hard work and show it off. Portfoliofy makes that process easier by doing all the screenshots for you and assembling them together into configurable, portfolio-ready files through a RESTful API interface.
(Sample of OUTPUT_MAIN - a multi-device viewport composite of art.gsa.gov showing desktop, laptop, tablet and smartphone views with stylized device mockups. More screenshots below.)
Portfoliofy is intended for:
- Student and professional web developers building portfolios to showcase their web development projects
- Self-directed learners looking to learn Python, in general, and RESTful API development using FastAPI, specifically, within the context of building a web screenshot generator and image manipulation application.
Portfoliofy v3.0.0-beta.3 exposes RESTful API endpoints that process HTTP requests for the following OUTPUT types, each offering configurable visual stylings, document layouts and output formats.
- Eye-catching composite of viewport-specific screenshots at multiple device resolutions (desktop, laptop, tablet, smartphone)
- Each screenshot overlaid on a stylized device mockup
- Supported formats: PNG, JPEG, BMP, TIFF, PDF
- Viewport-specific screenshot at desktop resolution, overlaid on a stylized browser mockup
- Supported formats: PNG, JPEG, BMP, TIFF, PDF
- Side-by-side composite of viewport-specific screenshots at tablet and smartphone resolutions
- Each screenshot overlaid on a stylized device mockup
- Supported formats: PNG, JPEG, BMP, TIFF, PDF
- Full-page screenshot of the entire webpage content from top to bottom, overlaid on a stylized browser mockup
- Supported formats: PNG, JPEG, BMP, TIFF
- A scroll animation video of a full-page screenshot, framed by a stylized browser mockup
- Supported format: MP4
- Plain, viewport-specific screenshots at the following resolutions:
- Desktop (2160x1360)
- Laptop (1440x900)
- Tablet (768x1024)
- Smartphone (230x490)
- Plain, full-page screenshot of the entire webpage content from top to bottom
- Supported formats: PNG, JPEG, BMP, TIFF, PDF (except for full-page)
portfoliofy/
│
├── api/
│ │
│ ├── core/
│ │ ├── config/
│ │ │ └── __init__.py
│ │ └── utils/
│ │ └── __init__.py
│ │
│ ├── domain/
│ │ ├── schemas/
│ │ │ └── __init__.py
│ │ └── services/
│ │ └── __init__.py
│ │
│ ├── output/
│ │
│ ├── routers/
│ │ ├── __init__.py
│ │ └── endpoints/
│ │ └── __init__.py
│ │
│ └── portfoliofy.py
│
├── assets/
├── .gitignore
├── .pylintrc
├── README.md
└── requirements.txt
For those who want to get up and running quickly with default settings:
# Clone repository
git clone https://github.com/ggeerraarrdd/portfoliofy.git
cd portfoliofy
# Set up environment
python3 -m venv venv
source venv/bin/activate # On Windows use `venv\Scripts\activate`
pip install -r requirements.txt
# Configure ChromeDriver path in .env file
echo "CHROMEDRIVER_PATH='/path/to/your/chromedriver'" > .env
# Start the server
python3 -m uvicorn api.portfoliofy:app --reload
# Access API documentation at http://127.0.0.1:8000/docs- Python 3.12
- Portfoliofy not fully tested on other versions
- Google Chrome
- Latest stable version recommended
- ChromeDriver
- Must match your Chrome browser version
- Download from the official ChromeDriver website
- Must be in system PATH or configured via
.env(see Configuration)
- See
requirements.txt
Note: CairoSVG may require additional systems libraries. Refer to their official documentation.
-
Clone the repository
git clone https://github.com/ggeerraarrdd/portfoliofy.git
-
Create and activate a virtual environment
python3 -m venv venv source venv/bin/activate # On Windows use `venv\Scripts\activate`
-
Install the dependencies
pip install -r requirements.txt
-
Configure the chromedriver path
- Create a
.envfile in the root directory of the project - Specify your ChromeDriver path:
CHROMEDRIVER_PATH='/path/to/your/chromedriver'
- Update path to match local ChromeDriver installation
- Create a
-
Start development server
python3 -m uvicorn api.portfoliofy:app --reload
-
Access the documentation user interfaces
The Portfoliofy REST API was built using FastAPI, which comes with two documentation user interfaces:
- Swagger UI: served at
/docs. - ReDoc: served at
/redoc.
The Swagger UI for Portfoliofy served at /docs - Swagger UI: served at
-
Choose an endpoint for your needs
POST /main-OUTPUT_MAINPOST /browser-OUTPUT_BROWSERPOST /mobiles-OUTPUT_MOBILESPOST /full-OUTPUT_FULLPOST /movie-OUTPUT_MOVIEPOST /screenshots/desktop- plain, viewport-specific screenshots at desktop resolution (2160x1360)POST /screenshots/laptop- plain, viewport-specific screenshots at laptop resolution (1440x900)POST /screenshots/tablet- plain, viewport-specific screenshots at tablet resolution (768x1024)POST /screenshots/smartphone- plain, viewport-specific screenshots at smartphone resolution (230x490)POST /screenshots/full- plain, full-page screenshot -
Configure your request parameters
This is the request body schema for all endpoints.
Parameter Type Default value Value range Description request bool False True, False If TRUE, requested OUTPUT type is processed remote_url string "https://ggeerraarrdd.github.io/" ... URL to portfoliofy wait int 2 1 - 100 Delay in seconds before capturing screenshot format string "png" "bmp", "jpeg", "mp4", "pdf", "png", "tiff" File format for API response document doc_pad_h int 300 1 - 1000 Horizontal padding in pixels between OUTPUT content and API response document edges doc_pad_v int 200 1 - 1000 Vertical padding in pixels between OUTPUT content and API response document edges doc_fill_color string "#FFFFFF" ... Background color of API response document in 6-digit hex base_stroke_color string "#23445D" ... Outline color of device mockup frame in 6-digit hex base_fill_color string "#BAC8D3" ... Background color of device mockup frame in 6-digit hex Example Request:
{ "request": true, "remote_url": "https://ggeerraarrdd.github.io/", "wait": 2, "format": "png", "doc_pad_h": 300, "doc_pad_v": 200, "doc_fill_color": "#ffffff", "base_stroke_color": "#23445d", "base_fill_color": "#bac8d3" }Additional Notes
POST /moviereturns204 NO CONTENTfor full-page heights ≥ 20,000px at 1280px width.POST /movieenforces MP4 output regardless of format parameter.
- TBD
- TBD
The initial release of Portfoliofy was submitted as a final project for CS50P: Introduction to Programming with Python (HarvardX, 2023). Read the project brief as of November 2023.
- Improvements and new features development are ongoing.
This project is not accepting contributions at this time. It is intended solely for personal learning and exploration. However, feel free to clone the repository and use it as a learning resource.
- Sanjeev Thiyagarajan's massive, 19-hour Python API Development course is
thebest online tutorial video I have watched not just on APIs but on any IT topic.
(From top to bottom: OUTPUT_BROWSER, OUTPUT_MOBILES, OUTPUT_FULL, OUTPUT_MOVIE for the US General Services Administration Fine Arts Collection website @ https://art.gsa.gov/)
portfoliofy5.mp4
Portfoliofy API. (2023). [Multi-device viewport composite of art.gsa.gov: Desktop, laptop, tablet, and smartphone views with stylized device mockups] [Digital output]. Author's collection. In the public domain.