OpenAPI (OAS) Format

The OpenAPI format imports API specifications in OpenAPI 3.x format, enabling integration with API design tools and automatic generation of data models from REST APIs.

Overview

The OAS format (identifier: oas) imports OpenAPI Specification (formerly Swagger) files defining REST APIs. It supports:

  • OpenAPI 3.0.x and 3.1.x specifications
  • JSON and YAML input formats
  • Schema definitions (components/schemas)
  • Request and response body schemas
  • Nested object structures
  • Array types and compositions (allOf, anyOf, oneOf)
  • Enum and constant value constraints

Format Identifier

Format: oas

File Extensions: .json, .yaml, .yml

MIME Type: application/vnd.oai.openapi+json

Direction Support

Direction Supported Version
Import Yes 1.0.0
Export No N/A

OpenAPI Schema Mapping

OpenAPI specification elements are mapped to Mauro as follows:

components/schemas
Each schema definition maps to a Mauro data class
object properties
Map to data elements within classes
$ref references
Resolved to reference type data elements linking to target classes
allOf
Properties from all schemas are merged into the parent class
anyOf / oneOf
Captured as metadata showing alternative schemas
enum
Maps to enumeration type data elements with value lists
array
Maps to data elements with multiplicity [0..*]
required
Sets minimum multiplicity to 1 for required properties

Examples

The following examples illustrate the use of the OpenAPI Specification format

Import OpenAPI JSON Specification

MauroImportExport.Cli import oas api-spec.json model.json

Import OpenAPI YAML Specification

MauroImportExport.Cli import oas swagger.yaml model.json --verbose

Convert OpenAPI to DITA Documentation

MauroImportExport.Cli convert oas dita api-spec.json documentation \
    --out-param dita.generateMaps=true

Supported OpenAPI Features

  • Data types: string, number, integer, boolean, object, array
  • String formats: date, date-time, email, uri, uuid, etc.
  • Numeric constraints: minimum, maximum, multipleOf
  • String constraints: minLength, maxLength, pattern
  • Array constraints: minItems, maxItems, uniqueItems
  • Object constraints: required, additionalProperties
  • Composition: allOf, anyOf, oneOf
  • References: $ref to components/schemas
  • Metadata: title, description, example, deprecated

API-Specific Handling

The OAS importer extracts data models from API specifications:

  • Path parameters and query parameters are captured as metadata
  • Request body schemas are imported as data classes
  • Response schemas (200, 201, etc.) are imported as classes
  • API info (title, version, description) is captured in model metadata
  • Security schemes are documented in metadata

Best Practices

  • Use JSON format for better parsing reliability
  • Ensure all $ref references point to valid schema components
  • Include description fields for better documentation
  • Use meaningful schema names that reflect domain concepts
  • Leverage allOf for schema inheritance and composition
  • Tag schemas with x-* extensions for tool-specific metadata
  • Validate OpenAPI files with validators before import

Use Cases

The OAS importer is particularly useful for:

  • Generating data dictionaries from API specifications
  • Creating data models for API client libraries
  • Documenting API request/response structures
  • Validating API design against data governance policies
  • Comparing API versions for breaking changes
  • Converting API schemas to other formats (DITA, JSON Schema)

Limitations

  • Import only (no OAS export currently available)
  • Focus on schema/data model extraction; paths and operations are metadata
  • Some OpenAPI 3.1 features may require specification compatibility
  • External $ref to other files requires manual consolidation

Integration with API Tools

The importer works with OpenAPI files from:

  • Swagger Editor and Swagger UI
  • Stoplight Studio
  • Postman collections exported as OpenAPI
  • API Gateway specifications (AWS, Azure, Google Cloud)
  • Code-first generators (Swashbuckle, SpringDoc, etc.)