https://github.com/algorithmalchemy/template-custom-swagger
Template repository for customizing the standard Swagger UI
https://github.com/algorithmalchemy/template-custom-swagger
custom-swagger fastapi swagger swagger-ui
Last synced: 3 months ago
JSON representation
Template repository for customizing the standard Swagger UI
- Host: GitHub
- URL: https://github.com/algorithmalchemy/template-custom-swagger
- Owner: AlgorithmAlchemy
- License: mit
- Created: 2025-09-07T13:00:30.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-09-08T05:34:09.000Z (4 months ago)
- Last Synced: 2025-09-08T07:17:16.681Z (4 months ago)
- Topics: custom-swagger, fastapi, swagger, swagger-ui
- Language: CSS
- Homepage:
- Size: 23.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Custom Swagger UI Template
[๐ฌ๐ง English](README.md) | [๐ท๐บ ะ ัััะบะธะน](README_ru.md) | [๐ช๐ธ Espaรฑol](README_es.md)
A template for customizing the standard Swagger UI. This template replaces the default top bar with a custom, brandable one, and adds features like API specification export, dark mode, and enhanced micro-interactions.
## โจ Features
- **Custom Branded Top Bar**: Easily add your company logo, custom links, and contact information.
- **API Specification Export**: Buttons to export the API definition in `JSON` and `YAML`, `PDF` formats.
- **Dark Mode**: A sleek, modern dark theme for the entire UI, toggleable by the user.
- **Responsive Design**: The custom UI is fully responsive and works on mobile devices.
- **Enhanced Micro-interactions**: Smooth animations, ripple effects on buttons, and scroll-to-top functionality for a better user experience.
- **Easy Integration**: Simply include the CSS and JavaScript files in your existing Swagger UI setup.
## ๐ Getting Started
### Prerequisites
You need to have a working Swagger UI instance. This template is designed to be an overlay on top of the standard Swagger UI.
### Installation
1. Clone this repository or download the files.
2. Copy the following files to the static assets directory of your web server where your Swagger UI is hosted:
- `custom-swagger.css`
- `custom-swagger.js`
- `swagger_custom.css`
- `swagger_custom.js`
### Usage
In your HTML file that serves Swagger UI, include the custom CSS and JavaScript files. Make sure to load them **after** the official Swagger UI assets.
```html
My API Docs
window.onload = function() {
// Build a system
const ui = SwaggerUIBundle({
url: "https://petstore.swagger.io/v2/swagger.json",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})
window.ui = ui
}
```
## ๐ง Configuration
You can customize the top bar by editing `custom-swagger.js`.
- **Logo and Links**: Find the `createBlueStrip` function and modify the `stripHTML` constant to change the logo, links, and text.
- **Export file names**: You can change the default names for exported files in the `download` attribute of the anchor tags within `stripHTML`.
The styles can be modified in `custom-swagger.css` and `swagger_custom.css`.
## ๐ File Structure
- `custom-swagger.js`: Handles the creation of the custom top bar and its elements.
- `custom-swagger.css`: Provides the styles for the custom top bar.
- `swagger_custom.js`: Contains logic for advanced features like theme switching, micro-interactions, and the scroll-to-top button.
- `swagger_custom.css`: Contains extensive styles for the dark theme, responsive design, and other UI enhancements.
## ๐ค Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## ๐ License
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.