mirror of
https://github.com/arsvendg/Stirling-PDF.git
synced 2026-07-14 10:34:06 +02:00
Swagger fixes (#5071)
# Description of Changes <!-- Please provide a summary of the changes, including: - What was changed - Why the change was made - Any challenges encountered Closes #(issue_number) --> --- ## Checklist ### General - [ ] I have read the [Contribution Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md) - [ ] I have read the [Stirling-PDF Developer Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md) (if applicable) - [ ] I have read the [How to add new languages to Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md) (if applicable) - [ ] I have performed a self-review of my own code - [ ] My changes generate no new warnings ### Documentation - [ ] I have updated relevant docs on [Stirling-PDF's doc repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/) (if functionality has heavily changed) - [ ] I have read the section [Add New Translation Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags) (for new translation tags only) ### Translations (if applicable) - [ ] I ran [`scripts/counter_translation.py`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docs/counter_translation.md) ### UI Changes (if applicable) - [ ] Screenshots or videos demonstrating the UI changes are attached (e.g., as comments or direct attachments in the PR) ### Testing (if applicable) - [ ] I have tested my changes locally. Refer to the [Testing Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing) for more details. Co-authored-by: Reece Browne <[email protected]>
This commit is contained in:
Anthony Stirling
co-authored by
Reece Browne
Reece Browne
parent
4ae79d92ae
commit
d908bc6785
@@ -22,25 +22,13 @@ import io.swagger.v3.oas.annotations.tags.Tag;
|
|||||||
name = "Analysis",
|
name = "Analysis",
|
||||||
description =
|
description =
|
||||||
"""
|
"""
|
||||||
Document analysis and information extraction services for content intelligence and insights.
|
Read-only inspection of PDFs: page count, page sizes, fonts, form fields, annotations, document properties, and security details.
|
||||||
|
Use these endpoints to understand what's inside a document without changing it.
|
||||||
|
|
||||||
This endpoint group provides analytical capabilities to understand document structure,
|
Typical uses:
|
||||||
extract information, and generate insights from PDF content for automated processing.
|
• Get page counts and dimensions for layout or print rules
|
||||||
|
• List fonts and annotations to spot compatibility issues
|
||||||
Common use cases:
|
• Inspect form fields before deciding how to fill or modify them
|
||||||
• Document inventory management and content audit for compliance verification
|
• Pull metadata and security settings for audits or reports
|
||||||
• Quality assurance workflows and business intelligence analytics
|
|
||||||
• Migration planning, accessibility evaluation, and document forensics
|
|
||||||
|
|
||||||
Business applications:
|
|
||||||
• Legal discovery, financial document review, and healthcare records analysis
|
|
||||||
• Academic research, government processing, and publishing optimization
|
|
||||||
|
|
||||||
Operational scenarios:
|
|
||||||
• Large-scale profiling, migration assessment, and performance optimization
|
|
||||||
• Automated quality control and content strategy development
|
|
||||||
|
|
||||||
Target users: Data analysts, QA teams, administrators, and business intelligence
|
|
||||||
professionals requiring detailed document insights.
|
|
||||||
""")
|
""")
|
||||||
public @interface AnalysisApi {}
|
public @interface AnalysisApi {}
|
||||||
|
|||||||
@@ -22,25 +22,13 @@ import io.swagger.v3.oas.annotations.tags.Tag;
|
|||||||
name = "Convert",
|
name = "Convert",
|
||||||
description =
|
description =
|
||||||
"""
|
"""
|
||||||
Document format transformation services for cross-platform compatibility and workflow integration.
|
Convert PDFs to and from other formats (Word, images, HTML, Markdown, PDF/A, CBZ/CBR, EML, etc.).
|
||||||
|
This group also powers the text-editor / jobId-based editing flow for incremental PDF edits.
|
||||||
|
|
||||||
This endpoint group enables transformation between various formats, supporting
|
Typical uses:
|
||||||
diverse business workflows and system integrations for mixed document ecosystems.
|
• Turn PDFs into Word or text for editing
|
||||||
|
• Convert office files, images, HTML, or email (EML) into PDFs
|
||||||
Common use cases:
|
• Create PDF/A for long-term archiving
|
||||||
• Legacy system integration, document migration, and cross-platform sharing
|
• Export PDFs as images, HTML, CSV, or Markdown for search, analysis, or reuse
|
||||||
• Archive standardization, publishing preparation, and content adaptation
|
|
||||||
• Accessibility compliance and mobile-friendly document preparation
|
|
||||||
|
|
||||||
Business applications:
|
|
||||||
• Enterprise content management, digital publishing, and educational platforms
|
|
||||||
• Legal document processing, healthcare interoperability, and government standardization
|
|
||||||
|
|
||||||
Integration scenarios:
|
|
||||||
• API-driven pipelines, automated workflow preparation, and batch conversions
|
|
||||||
• Real-time format adaptation for user requests
|
|
||||||
|
|
||||||
Target users: System integrators, content managers, digital archivists, and
|
|
||||||
organizations requiring flexible document format interoperability.
|
|
||||||
""")
|
""")
|
||||||
public @interface ConvertApi {}
|
public @interface ConvertApi {}
|
||||||
|
|||||||
@@ -22,25 +22,13 @@ import io.swagger.v3.oas.annotations.tags.Tag;
|
|||||||
name = "Filter",
|
name = "Filter",
|
||||||
description =
|
description =
|
||||||
"""
|
"""
|
||||||
Document content filtering and search operations for information discovery and organization.
|
Check basic properties of PDFs before you process them: page count, file size, page size/rotation, and whether they contain text or images.
|
||||||
|
Use these endpoints as a "pre-check" step to decide what to do with a file next.
|
||||||
|
|
||||||
This endpoint group enables intelligent content discovery and organization within
|
Typical uses:
|
||||||
document collections for content-based processing and information extraction.
|
• Reject files that are too big or too small
|
||||||
|
• Detect image-only PDFs that should go through OCR
|
||||||
Common use cases:
|
• Ensure a document has enough pages before it enters a workflow
|
||||||
• Legal discovery, research organization, and compliance auditing
|
• Check orientation of pages before printing or merging
|
||||||
• Content moderation, academic research, and business intelligence
|
|
||||||
• Quality assurance and content validation workflows
|
|
||||||
|
|
||||||
Business applications:
|
|
||||||
• Contract analysis, financial review, and healthcare records organization
|
|
||||||
• Government processing, educational curation, and IP protection
|
|
||||||
|
|
||||||
Workflow scenarios:
|
|
||||||
• Large-scale processing, automated classification, and information extraction
|
|
||||||
• Document preparation for further processing or analysis
|
|
||||||
|
|
||||||
Target users: Legal professionals, researchers, compliance officers, and
|
|
||||||
organizations requiring intelligent document content discovery and organization.
|
|
||||||
""")
|
""")
|
||||||
public @interface FilterApi {}
|
public @interface FilterApi {}
|
||||||
|
|||||||
@@ -22,21 +22,13 @@ import io.swagger.v3.oas.annotations.tags.Tag;
|
|||||||
name = "General",
|
name = "General",
|
||||||
description =
|
description =
|
||||||
"""
|
"""
|
||||||
Core PDF processing operations for fundamental document manipulation workflows.
|
Page-level PDF editing: split, merge, rotate, crop, rearrange, and scale pages.
|
||||||
|
These endpoints handle most daily "I opened a PDF editor just to…" type tasks.
|
||||||
|
|
||||||
This endpoint group provides essential PDF functionality that forms the foundation
|
Typical uses:
|
||||||
of most document processing workflows across various industries.
|
• Split a large PDF into smaller files (by pages, chapters, or size)
|
||||||
|
• Merge several PDFs into one report or pack
|
||||||
Common use cases:
|
• Rotate or reorder pages before sending or archiving
|
||||||
• Document preparation for archival systems and content organization
|
• Turn a multi-page document into one long scrolling page
|
||||||
• File preparation for distribution, accessibility compliance, and batch processing
|
|
||||||
• Document consolidation for reporting and legal compliance workflows
|
|
||||||
|
|
||||||
Typical applications:
|
|
||||||
• Content management, publishing workflows, and educational content distribution
|
|
||||||
• Business process automation and archive management
|
|
||||||
|
|
||||||
Target users: Content managers, document processors, and organizations requiring
|
|
||||||
reliable foundational PDF manipulation capabilities.
|
|
||||||
""")
|
""")
|
||||||
public @interface GeneralApi {}
|
public @interface GeneralApi {}
|
||||||
|
|||||||
@@ -22,25 +22,15 @@ import io.swagger.v3.oas.annotations.tags.Tag;
|
|||||||
name = "Misc",
|
name = "Misc",
|
||||||
description =
|
description =
|
||||||
"""
|
"""
|
||||||
Specialized utilities and supplementary tools for enhanced document processing workflows.
|
Tools that don't fit neatly elsewhere: OCR, compress, repair, flatten, extract images, update metadata, add stamps/page numbers/images, and more.
|
||||||
|
These endpoints help fix problem PDFs and prepare them for sharing, storage, or further processing.
|
||||||
|
|
||||||
This endpoint group provides utility operations that support core document processing
|
Typical uses:
|
||||||
tasks and address specific workflow needs in real-world scenarios.
|
• Repair a damaged PDF or remove blank pages
|
||||||
|
• Run OCR on scanned PDFs so they become searchable
|
||||||
Common use cases:
|
• Compress large PDFs for email or web download
|
||||||
• Document optimization for bandwidth-limited environments and storage cost management
|
• Extract embedded images or scans
|
||||||
• Document repair, content extraction, and validation for quality assurance
|
• Add page numbers, stamps, or overlay an image (e.g. logo, seal)
|
||||||
• Accessibility improvement and custom processing for specialized needs
|
• Update PDF metadata (title, author, etc.)
|
||||||
|
|
||||||
Business applications:
|
|
||||||
• Web publishing optimization, email attachment management, and archive efficiency
|
|
||||||
• Mobile compatibility, print production, and legacy document recovery
|
|
||||||
|
|
||||||
Operational scenarios:
|
|
||||||
• Batch processing, quality control, and performance optimization
|
|
||||||
• Troubleshooting and recovery of problematic documents
|
|
||||||
|
|
||||||
Target users: System administrators, document specialists, and organizations requiring
|
|
||||||
specialized document processing and optimization tools.
|
|
||||||
""")
|
""")
|
||||||
public @interface MiscApi {}
|
public @interface MiscApi {}
|
||||||
|
|||||||
@@ -22,25 +22,12 @@ import io.swagger.v3.oas.annotations.tags.Tag;
|
|||||||
name = "Pipeline",
|
name = "Pipeline",
|
||||||
description =
|
description =
|
||||||
"""
|
"""
|
||||||
Automated document processing workflows for complex multi-stage business operations.
|
Run several PDF operations in one configured pipeline instead of calling multiple endpoints yourself.
|
||||||
|
Useful when you always do the same steps in sequence (for example: convert → OCR → compress → watermark).
|
||||||
|
|
||||||
This endpoint group enables organizations to create sophisticated document processing
|
Typical uses:
|
||||||
workflows that combine multiple operations into streamlined, repeatable processes.
|
• Process incoming invoices in one go (clean, OCR, compress, stamp, etc.)
|
||||||
|
• Normalise documents before they enter an archive
|
||||||
Common use cases:
|
• Wrap a complex document flow behind a single API call for your own apps
|
||||||
• Invoice processing, legal document review, and healthcare records standardization
|
|
||||||
• Government processing, educational content preparation, and publishing automation
|
|
||||||
• Contract lifecycle management and approval processes
|
|
||||||
|
|
||||||
Business applications:
|
|
||||||
• Automated compliance reporting, large-scale migration, and quality assurance
|
|
||||||
• Archive preparation, content delivery, and document approval workflows
|
|
||||||
|
|
||||||
Operational scenarios:
|
|
||||||
• Scheduled batch processing and event-driven document processing
|
|
||||||
• Multi-department coordination and business system integration
|
|
||||||
|
|
||||||
Target users: Business process managers, IT automation specialists, and organizations
|
|
||||||
requiring consistent, repeatable document processing workflows.
|
|
||||||
""")
|
""")
|
||||||
public @interface PipelineApi {}
|
public @interface PipelineApi {}
|
||||||
|
|||||||
@@ -22,25 +22,13 @@ import io.swagger.v3.oas.annotations.tags.Tag;
|
|||||||
name = "Security",
|
name = "Security",
|
||||||
description =
|
description =
|
||||||
"""
|
"""
|
||||||
Document security and protection services for confidential and sensitive content.
|
Protect and clean PDFs: passwords, digital signatures, redaction, and sanitizing.
|
||||||
|
These endpoints help you control who can open a file, what they can do with it, and remove sensitive content when needed.
|
||||||
|
|
||||||
This endpoint group provides essential security operations for organizations handling
|
Typical uses:
|
||||||
sensitive documents and materials requiring controlled access.
|
• Add or remove a password on a PDF
|
||||||
|
• Redact personal or confidential information (manually or automatically)
|
||||||
Common use cases:
|
• Validate or remove digital signatures
|
||||||
• Legal confidentiality, healthcare privacy (HIPAA), and financial regulatory compliance
|
• Sanitize a PDF to strip scripts and embedded content
|
||||||
• Government classified handling, corporate IP protection, and educational privacy (FERPA)
|
|
||||||
• Contract security for business transactions
|
|
||||||
|
|
||||||
Business applications:
|
|
||||||
• Document authentication, confidential sharing, and secure archiving
|
|
||||||
• Content watermarking, access control, and privacy protection through redaction
|
|
||||||
|
|
||||||
Industry scenarios:
|
|
||||||
• Legal discovery, medical records exchange, financial audit documentation
|
|
||||||
• Enterprise policy enforcement and data governance
|
|
||||||
|
|
||||||
Target users: Legal professionals, healthcare administrators, compliance officers,
|
|
||||||
government agencies, and enterprises handling sensitive content.
|
|
||||||
""")
|
""")
|
||||||
public @interface SecurityApi {}
|
public @interface SecurityApi {}
|
||||||
|
|||||||
@@ -21,6 +21,9 @@ public class SpringDocConfig {
|
|||||||
"/api/v1/user/**",
|
"/api/v1/user/**",
|
||||||
"/api/v1/settings/**",
|
"/api/v1/settings/**",
|
||||||
"/api/v1/team/**",
|
"/api/v1/team/**",
|
||||||
|
"/api/v1/auth/**",
|
||||||
|
"/api/v1/invite/**",
|
||||||
|
"/api/v1/audit/**",
|
||||||
"/api/v1/ui-data/**",
|
"/api/v1/ui-data/**",
|
||||||
"/api/v1/proprietary/ui-data/**",
|
"/api/v1/proprietary/ui-data/**",
|
||||||
"/api/v1/info/**",
|
"/api/v1/info/**",
|
||||||
@@ -33,7 +36,7 @@ public class SpringDocConfig {
|
|||||||
openApi.getInfo()
|
openApi.getInfo()
|
||||||
.title("Stirling PDF - Processing API")
|
.title("Stirling PDF - Processing API")
|
||||||
.description(
|
.description(
|
||||||
"API documentation for PDF processing operations including conversion, manipulation, security, and utilities."));
|
"APIs for converting, editing, securing, and analysing PDF documents. Use these endpoints to automate common PDF tasks (like split, merge, convert, OCR) and plug them into your own apps and backend jobs."));
|
||||||
})
|
})
|
||||||
.build();
|
.build();
|
||||||
}
|
}
|
||||||
@@ -47,14 +50,17 @@ public class SpringDocConfig {
|
|||||||
"/api/v1/admin/**",
|
"/api/v1/admin/**",
|
||||||
"/api/v1/user/**",
|
"/api/v1/user/**",
|
||||||
"/api/v1/settings/**",
|
"/api/v1/settings/**",
|
||||||
"/api/v1/team/**")
|
"/api/v1/team/**",
|
||||||
|
"/api/v1/auth/**",
|
||||||
|
"/api/v1/invite/**",
|
||||||
|
"/api/v1/audit/**")
|
||||||
.addOpenApiCustomizer(
|
.addOpenApiCustomizer(
|
||||||
openApi -> {
|
openApi -> {
|
||||||
openApi.info(
|
openApi.info(
|
||||||
openApi.getInfo()
|
openApi.getInfo()
|
||||||
.title("Stirling PDF - Admin API")
|
.title("Stirling PDF - Management API")
|
||||||
.description(
|
.description(
|
||||||
"API documentation for administrative functions, user management, and system configuration."));
|
"Endpoints for authentication, user management, invitations, audit logging, and system configuration."));
|
||||||
})
|
})
|
||||||
.build();
|
.build();
|
||||||
}
|
}
|
||||||
@@ -76,7 +82,7 @@ public class SpringDocConfig {
|
|||||||
openApi.getInfo()
|
openApi.getInfo()
|
||||||
.title("Stirling PDF - System API")
|
.title("Stirling PDF - System API")
|
||||||
.description(
|
.description(
|
||||||
"API documentation for system information, UI data, and utility endpoints."));
|
"System information, UI metadata, job status, and file management endpoints."));
|
||||||
})
|
})
|
||||||
.build();
|
.build();
|
||||||
}
|
}
|
||||||
|
|||||||
+13
-1
@@ -34,7 +34,19 @@ import stirling.software.proprietary.util.FormUtils;
|
|||||||
|
|
||||||
@RestController
|
@RestController
|
||||||
@RequestMapping("/api/v1/form")
|
@RequestMapping("/api/v1/form")
|
||||||
@Tag(name = "Forms", description = "PDF form APIs")
|
@Tag(
|
||||||
|
name = "Forms",
|
||||||
|
description =
|
||||||
|
"""
|
||||||
|
Work with PDF form fields: read them, fill them, edit them, or remove them.
|
||||||
|
Treats a PDF as a structured form instead of just flat pages.
|
||||||
|
|
||||||
|
Typical uses:
|
||||||
|
• Inspect which form fields exist in a PDF
|
||||||
|
• Autofill forms from your own systems (e.g. CRM, ERP)
|
||||||
|
• Change or delete form fields before sending out a final, non-editable copy
|
||||||
|
• Unlock read-only form fields when you need to update them
|
||||||
|
""")
|
||||||
@RequiredArgsConstructor
|
@RequiredArgsConstructor
|
||||||
public class FormFillController {
|
public class FormFillController {
|
||||||
|
|
||||||
|
|||||||
@@ -51,6 +51,18 @@ export default defineConfig(({ mode }) => {
|
|||||||
secure: false,
|
secure: false,
|
||||||
xfwd: true,
|
xfwd: true,
|
||||||
},
|
},
|
||||||
|
'/swagger-ui': {
|
||||||
|
target: 'http://localhost:8080',
|
||||||
|
changeOrigin: true,
|
||||||
|
secure: false,
|
||||||
|
xfwd: true,
|
||||||
|
},
|
||||||
|
'/v1/api-docs': {
|
||||||
|
target: 'http://localhost:8080',
|
||||||
|
changeOrigin: true,
|
||||||
|
secure: false,
|
||||||
|
xfwd: true,
|
||||||
|
},
|
||||||
},
|
},
|
||||||
},
|
},
|
||||||
base: process.env.RUN_SUBPATH ? `/${process.env.RUN_SUBPATH}` : './',
|
base: process.env.RUN_SUBPATH ? `/${process.env.RUN_SUBPATH}` : './',
|
||||||
|
|||||||
Reference in New Issue
Block a user