Import the API reference spec file

25 Nov 2023
4 Minutes to read
Contributors

Print
Share
Dark
Light

Import the API reference spec file

Updated on 25 Nov 2023
4 Minutes to read
Contributors

Print
Share
Dark
Light

Article Summary

Share feedback

Thanks for sharing your feedback!

Post

/v2/APIReferences

Security

API Key

Header parameter nameapi_token

Enter REST API key. To generate a key, go to Settings → Knowledge base portal → API tokens

Body parameters

Add API reference request

Import an API reference with projectVersionId, userId and a spec file url or a file type.

{
  "project_version_id": "5b291e6b-fa40-4ab9-941e-f8fffc23b376",
  "user_id": "46f48bc7-760f-4b07-b2d2-fce4aa8ba234",
  "force_import": true,
  "url": "https://petstore.swagger.io/v2/swagger.json",
  "file": null
}

object

ProjectVersionId

string Required

The ID of the project version

UserId

string Required

The ID of the team account

ForceImport

boolean Required

true : The errors and alerts will not be shown while importing the spec file
false : The errors and alerts will be shown while importing the spec file

Default"True"

Url

string

Url of the spec file

File

string (binary)

File path of the spec file

Responses

200

Success

Success status Response

This is the sample response for single API reference import with server variables.

{
  "data": {
    "categories_created": 23,
    "articles_created": 23,
    "api_reference_id": "9874c1d9-033f-484c-8e3e-c343301eae57",
    "errors": [],
    "alerts": []
  },
  "extension_data": null,
  "success": true,
  "errors": [],
  "warnings": [],
  "information": []
}

Success status Response with no server variables

This is the sample response for single API reference import without server variables.

{
  "data": {
    "categories_created": 3,
    "articles_created": 23,
    "api_reference_id": "9874c1d9-033f-484c-8e3e-c343301eae57",
    "errors": [],
    "alerts": []
  },
  "extension_data": null,
  "success": true,
  "errors": [],
  "warnings": [
    {
      "extension_data": null,
      "description": "You may not be able to use try-it feature. Looks like server variables aren’t defined in your OpenAPI Specification file.",
      "warning_code": null
    }
  ],
  "information": []
}

Success status Response for ForceImport as false

This is the sample response for single API reference import with force import as false.

{
  "data": {
    "categories_created": 3,
    "articles_created": 23,
    "api_reference_id": "9874c1d9-033f-484c-8e3e-c343301eae57",
    "errors": [
      {
        "message": "Declared path parameter 'contentId' needs to be defined as a path parameter at either the path or operation level",
        "pointer": "#/paths/~1v2~1Content~1{Id}~1version~1{contentCategoryId}/delete/parameters/2/in"
      }
    ],
    "alerts": [
      {
        "message": "Data and type mismatch found.",
        "pointer": "#/paths/~1v2~1Content/{Id}/depete/response/200/content/application~1json/examples/Content"
      }
    ]
  },
  "extension_data": null,
  "success": true,
  "errors": [],
  "warnings": [],
  "information": []
}

Expand All

object

data

object (ApiDocsImportDataCustomer)

categories_created

integer (int32)

Total category created

articles_created

integer (int32)

Total article created

api_reference_id

string

Api reference ID

errors

Array of object (ApiErrorAndWarningsData)

Error log response

object

message

string

Descriptive message of the problem

pointer

string

Path where the problem occures

alerts

Array of object (ApiErrorAndWarningsData)

Alerts log response

object

message

string

Descriptive message of the problem

pointer

string

Path where the problem occures

extension_data

object (ExtensionDataObject)

success

boolean

Status indication for customer API response

errors

Array of object (BaseError)

Errors in the customer API response

object

extension_data

object (ExtensionDataObject)

stack_trace

string

Stack trace for error response message

description

string

Description for error cause

error_code

string

Error code for Api response

custom_data

object

warnings

Array of object (BaseWarning)

Warning in the customer API response

object

extension_data

object (ExtensionDataObject)

description

string

Warning description

warning_code

string

warning code for customer Api base response

information

Array of object (BaseInformation)

Information passed by the customer API response

object

extension_data

object (ExtensionDataObject)

description

string

status description for customer Api response information

400

Bad Request

Inalid project Version ID

Kindly ensure that the given project version ID is valid.

{
  "data": null,
  "extension_data": null,
  "success": false,
  "errors": [
    {
      "extension_data": null,
      "stack_trace": null,
      "description": "The supplied project version id d2eafb73-ccb6-4d15-9c4a-959b3c232ddba does not exist in your project",
      "error_code": null,
      "custom_data": null
    }
  ],
  "warnings": [],
  "information": []
}

Inalid user ID

Kindly ensure that the given user ID is valid.

{
  "data": null,
  "extension_data": null,
  "success": false,
  "errors": [
    {
      "extension_data": null,
      "stack_trace": null,
      "description": "The user with id 'f11efc6f-e968-4e95-82eb-85ad61559de8a' does not exist in your project.",
      "error_code": null,
      "custom_data": null
    }
  ],
  "warnings": [],
  "information": []
}

Maximum API Reference limit reached

You had reached your maximum API reference limit, for continuing add a new version.

{
  "data": null,
  "extension_data": null,
  "success": false,
  "errors": [
    {
      "extension_data": null,
      "stack_trace": null,
      "description": "Unable to add API Reference: Maximum API Reference limit reached",
      "error_code": null,
      "custom_data": null
    }
  ],
  "warnings": [],
  "information": []
}

Supplied URL is invalid

You have to provide a valid OAS spec file URL.

{
  "data": null,
  "extension_data": null,
  "success": false,
  "errors": [
    {
      "extension_data": null,
      "stack_trace": null,
      "description": "Invalid Url",
      "error_code": null,
      "custom_data": null
    }
  ],
  "warnings": [],
  "information": []
}

Can`t upload both the file and the URL

You have to provide only a valid OAS spec file or a spec file URL.

{
  "data": null,
  "extension_data": null,
  "success": false,
  "errors": [
    {
      "extension_data": null,
      "stack_trace": null,
      "description": "You can only upload URL or a spec file.",
      "error_code": null,
      "custom_data": null
    }
  ],
  "warnings": [],
  "information": []
}

Supplied file type is invalid

You have to upload a valid JSON or a YAML file.

{
  "data": null,
  "extension_data": null,
  "success": false,
  "errors": [
    {
      "extension_data": null,
      "stack_trace": null,
      "description": "Only YAML or JSON files are allowed.",
      "error_code": null,
      "custom_data": null
    }
  ],
  "warnings": [],
  "information": []
}

Expand All

object

data

object (ApiDocsImportDataCustomer)

categories_created

integer (int32)

Total category created

articles_created

integer (int32)

Total article created

api_reference_id

string

Api reference ID

errors

Array of object (ApiErrorAndWarningsData)

Error log response

object

message

string

Descriptive message of the problem

pointer

string

Path where the problem occures

alerts

Array of object (ApiErrorAndWarningsData)

Alerts log response

object

message

string

Descriptive message of the problem

pointer

string

Path where the problem occures

extension_data

object (ExtensionDataObject)

success

boolean

Status indication for customer API response

errors

Array of object (BaseError)

Errors in the customer API response

object

extension_data

object (ExtensionDataObject)

stack_trace

string

Stack trace for error response message

description

string

Description for error cause

error_code

string

Error code for Api response

custom_data

object

warnings

Array of object (BaseWarning)

Warning in the customer API response

object

extension_data

object (ExtensionDataObject)

description

string

Warning description

warning_code

string

warning code for customer Api base response

information

Array of object (BaseInformation)

Information passed by the customer API response

object

extension_data

object (ExtensionDataObject)

description

string

status description for customer Api response information

Was this article helpful?

What's Next

Resync the API reference spec file