swagger-api/swagger-core
Swagger Core
swagger-core is a set of libraries for parsing, generating, and serializing OpenAPI specifications to automate REST API documentation. It provides tools to read, validate, and transform JSON or YAML specifications into programmable objects, as well as a generator that scans source code and annotations to create formal technical descriptions of an API.
The project enables bi-directional specification serialization, allowing in-memory API definitions to be converted between native language objects and structured files. It uses a plugin-based scanning mechanism and annotation-driven generation to map application resources to specification operations, with support for intercepting the pipeline to modify or filter the resulting output.
The library covers a broad range of API modeling capabilities, including the definition of request parameters, response schemas, security schemes, and data model constraints. It also manages specification processing through reference resolution, schema conversion, and validation against formal specification rules.
Automation utilities are available to resolve and generate specification files during the build process.
Features
- Annotation-Driven Specification Generation - Automatically constructs technical API definitions by scanning source code for metadata annotations.
- Specification from Code Generators - Produces OpenAPI/Swagger specification documents by scanning annotated source code.
- API Documentation Tools - Provides a complete system for modeling API parameters, response schemas, and server metadata to automate REST documentation.
- JSON Schema Modeling - Provides structured data modeling for request and response validation using schemas.
- API Resource Scanning - Identifies endpoints to include in the specification by analyzing application instances or annotations.
- OpenAPI Specification Generators - Scans source code and annotations to automatically generate structured OpenAPI JSON or YAML specification files.
- OpenAPI Specification Parsers - Parses OpenAPI JSON and YAML definitions into internal representations for processing and analysis.
- OpenAPI Specification Serializers - Converts in-memory API object representations back into valid JSON or YAML specification documents.
- OpenAPI Schema Generators - Generates OpenAPI specification documents by scanning resource classes or converting models into schemas.
- Operation Descriptions - Maps methods to operations using summaries and detailed descriptions to explain API functionality.
- Class-to-Schema Conversion - Transforms application data classes into formal OpenAPI schemas by analyzing their types and constraints.
- Object Mapping APIs - Maps formal API specifications to a programmable set of objects for transformation and manipulation.
- OpenAPI Specification Management - Provides comprehensive tools for creating, validating, and transforming OpenAPI JSON or YAML files to maintain standard web service contracts.
- OpenAPI Specification Validators - Validates OpenAPI documents against formal specification rules to identify structural inconsistencies.
- OpenAPI Response Definitions - Implements mechanisms for defining API response schemas and status codes for every operation.
- API Metadata - Provides systems for defining API endpoints and schemas using annotations to include metadata not inferable from code.
- Input Parameter Specifications - Provides declarative definitions of path, query, and header variables that API endpoints accept.
- Media Type Definitions - Defines the content and media formats for parameters, request bodies, and responses.
- Request Body Documentation - Provides specification of the structure and requirements for incoming API request payloads.
- REST API Specifications - Allows the definition of request payloads, response schemas, and security requirements within the API specification.
- Automated Generation - Automatically generates OpenAPI specifications from application code to provide technical references for API consumers.
- API Specification Tooling Integration - Produces standardized specification files that enable third-party tools to generate client libraries and interactive API explorers.
- Build-Time Specification Exports - Generates static API specification files during the build process using specialized plugins.
- API Contract Synchronization - Automates the synchronization of technical API documentation with live code changes to maintain contract consistency.
- Specification Exposure - Serves the technical specification as a file via dedicated resources for client consumption.
- Structured Documentation Generation - Creates structured documentation for endpoints and authentication based on a formal specification.
- Plugin-Based Scanning Frameworks - Uses a plugin-based scanning mechanism to identify application endpoints and map them to operations.
- Security Scheme Documentation - Defines security mechanisms and documents authentication requirements for specific API operations within the specification.
- API Reference Resolution - Bundles internal and external references within a document to consolidate all content.
- Bi-Directional Specification Serialization - Enables seamless conversion of API definitions between native language objects and JSON/YAML files.
- Named Schema References - Resolves internal and external references within the specification to bundle related data models.
- Specification Generation Interceptors - The library executes custom logic before or after the scanning process to pre process or post process the specification.
- Specification Pipeline Interception - Provides hooks to modify or filter the generated API specification before it is finalized.
- Global API Metadata - Allows setting global properties including titles, versions, and contact information for the technical specification.
