OpenAPI Specification Converter

Public

API Details

This API converts existing OpenAPI Specifications (OAS) to the latest OpenAPI 3.1.0 version. It takes an input OAS document in JSON or YAML format and transforms it into a compliant OAS 3.1.0 specification. The converter handles various versions of OAS, including 2.0 (Swagger) and 3.0.x, updating the structure, syntax, and features to align with the 3.1.0 standard. This service is essential for API developers and maintainers who want to leverage the latest capabilities of OpenAPI 3.1.0, such as improved JSON Schema support, enhanced security schemes, and more flexible parameter serialization.

Request Schema

{
  "type": "object",
  "required": [
    "specification"
  ],
  "properties": {
    "outputFormat": {
      "enum": [
        "json",
        "yaml"
      ],
      "type": "string",
      "default": "json",
      "description": "The desired output format for the converted specification."
    },
    "specification": {
      "type": "string",
      "description": "The original OpenAPI Specification document in JSON or YAML format."
    }
  }
}

Response Schema

{
  "type": "object",
  "required": [
    "convertedSpecification",
    "version"
  ],
  "properties": {
    "version": {
      "type": "string",
      "const": "3.1.0",
      "description": "The version of the OpenAPI Specification to which the document was converted."
    },
    "conversionNotes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Any notes or warnings generated during the conversion process."
    },
    "convertedSpecification": {
      "type": "string",
      "description": "The converted OpenAPI 3.1.0 specification in the requested format (JSON or YAML)."
    }
  }
}

API Metadata

656

Version

API Examples

Example Request

{
  "outputFormat": "json",
  "specification": "{ \"swagger\": \"2.0\", \"info\": { \"title\": \"Sample API\", \"version\": \"1.0.0\" }, \"paths\": { \"/users\": { \"get\": { \"summary\": \"List users\", \"responses\": { \"200\": { \"description\": \"Successful response\" } } } } } }"
}

Example Response

{
  "version": "3.1.0",
  "conversionNotes": [
    "Converted from Swagger 2.0 to OpenAPI 3.1.0",
    "Updated 'swagger' field to 'openapi'",
    "No schema changes were required for this simple specification"
  ],
  "convertedSpecification": "{ \"openapi\": \"3.1.0\", \"info\": { \"title\": \"Sample API\", \"version\": \"1.0.0\" }, \"paths\": { \"/users\": { \"get\": { \"summary\": \"List users\", \"responses\": { \"200\": { \"description\": \"Successful response\" } } } } } }"
}