--- title: "Preview API Spec" url: "https://us-prod.jeffyongtaotang.com/apis/konnect-service-catalog-1/versions/cdbef9b7-686c-4189-bbc8-55c727a972e8/operations/preview-catalog-service-api-spec" --- > Full API specification: https://us-prod.jeffyongtaotang.com/apis/konnect-service-catalog-1/versions/cdbef9b7-686c-4189-bbc8-55c727a972e8.md # Preview API Spec `POST` `/catalog-services/{serviceId}/api-specs/preview` Operation ID: `preview-catalog-service-api-spec` Previews the contents of an API spec as JSON or YAML. Specify `Accept: application/json` to retrieve the contents as JSON. Specify `Accept: application/yaml` to retrieve the contents as YAML. Defaults to JSON format. ## Path parameters - `serviceId` (string, required) - The `id` of the service. ## Request body (required) Content types: `application/json` ## Responses - `200` - Response object containing raw API spec contents - `400` - Bad Request - `401` - Unauthorized - `403` - Forbidden - `404` - Not Found ## OpenAPI definition ```yaml openapi: 3.0.3 info: title: Konnect Service Catalog version: 1.3.0 servers: - url: https://us.api.konghq.com/v1 description: United-States Production region - url: https://eu.api.konghq.com/v1 description: Europe Production region - url: https://au.api.konghq.com/v1 description: Australia Production region - url: https://me.api.konghq.com/v1 description: Middle-East Production region - url: https://in.api.konghq.com/v1 description: India Production region - url: https://sg.api.konghq.com/v1 description: Singapore Production region paths: /catalog-services/{serviceId}/api-specs/preview: parameters: - schema: type: string example: 7f9fd312-a987-4628-b4c5-bb4f4fddd5f7 name: serviceId in: path required: true description: The `id` of the service. post: x-unstable: true x-internal: true summary: Preview API Spec operationId: preview-catalog-service-api-spec description: | Previews the contents of an API spec as JSON or YAML. Specify `Accept: application/json` to retrieve the contents as JSON. Specify `Accept: application/yaml` to retrieve the contents as YAML. Defaults to JSON format. requestBody: $ref: "#/components/requestBodies/PreviewCatalogServiceApiRequest" responses: "200": $ref: "#/components/responses/CatalogServiceApiSpecPreviewResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" tags: - Catalog Service API Specs security: - konnectAccessToken: [] - personalAccessToken: [] - systemAccountAccessToken: [] components: requestBodies: PreviewCatalogServiceApiRequest: required: true content: application/json: schema: $ref: "#/components/schemas/PreviewCatalogServiceApiSpec" examples: Url: $ref: "#/components/examples/PreviewServiceApiUrlPayload" Raw: $ref: "#/components/examples/PreviewServiceApiRawPayload" Integration: $ref: "#/components/examples/PreviewServiceApiIntegrationPayload" Resource: $ref: "#/components/examples/PreviewServiceApiResourcePayload" responses: CatalogServiceApiSpecPreviewResponse: description: Response object containing raw API spec contents content: application/json: schema: $ref: "#/components/schemas/ApiSpecContents" examples: JSON: $ref: "#/components/examples/PreviewServiceApiResponseJson" application/yaml: schema: $ref: "#/components/schemas/ApiSpecContentsYaml" examples: YAML: $ref: "#/components/examples/PreviewServiceApiResponseYaml" BadRequest: description: Bad Request content: application/problem+json: schema: $ref: "#/components/schemas/BadRequestError" Unauthorized: description: Unauthorized content: application/problem+json: schema: $ref: "#/components/schemas/UnauthorizedError" examples: UnauthorizedExample: $ref: "#/components/examples/UnauthorizedExample" Forbidden: description: Forbidden content: application/problem+json: schema: $ref: "#/components/schemas/ForbiddenError" examples: UnauthorizedExample: $ref: "#/components/examples/ForbiddenExample" NotFound: description: Not Found content: application/problem+json: schema: $ref: "#/components/schemas/NotFoundError" examples: NotFoundExample: $ref: "#/components/examples/NotFoundExample" schemas: PreviewCatalogServiceApiSpec: type: object additionalProperties: false required: - provider properties: provider: title: CreateApiSpecProvider description: Represents the provider, or source, of an API spec oneOf: - $ref: "#/components/schemas/UrlApiSpecProvider" - $ref: "#/components/schemas/RawApiSpecProviderPayload" - $ref: "#/components/schemas/IntegrationApiSpecProviderPayload" - $ref: "#/components/schemas/ResourceBoundIntegrationApiSpecProviderPayload" ApiSpecContents: title: ApiSpecContents description: Represents raw API spec contents type: object additionalProperties: true example: openapi: 3.0.0 info: version: 1.0.0 title: Swagger Petstore servers: - url: http://petstore.swagger.io/v1 paths: {} ApiSpecContentsYaml: title: ApiSpecContentsYaml description: Represents raw API spec contents type: string BadRequestError: allOf: - $ref: "#/components/schemas/BaseError" - type: object required: - invalid_parameters properties: invalid_parameters: $ref: "#/components/schemas/InvalidParameters" UnauthorizedError: allOf: - $ref: "#/components/schemas/BaseError" - type: object properties: status: example: 401 title: example: Unauthorized type: example: https://httpstatuses.com/401 instance: example: kong:trace:1234567890 detail: example: Invalid credentials ForbiddenError: allOf: - $ref: "#/components/schemas/BaseError" - type: object properties: status: example: 403 title: example: Forbidden type: example: https://httpstatuses.com/403 instance: example: kong:trace:1234567890 detail: example: Forbidden NotFoundError: allOf: - $ref: "#/components/schemas/BaseError" - type: object properties: status: example: 404 title: example: Not Found type: example: https://httpstatuses.com/404 instance: example: kong:trace:1234567890 detail: example: Not found UrlApiSpecProvider: type: object required: - type - config properties: type: type: string enum: - url config: type: object required: - url properties: url: type: string format: uri description: | Public URL that resolves to the raw API spec contents. Supported formats are JSON and YAML. example: https://api.petstore.com/v3/openapi.json RawApiSpecProviderPayload: type: object properties: type: type: string enum: - raw config: title: RawApiSpecProviderConfig type: object additionalProperties: false properties: contents: type: string description: | Raw API spec file contents. Supports JSON or YAML format. Raw specs have a maximum size limit of 8mb. example: | {"openapi":"3.0.0","info":{"version":"1.0.0","title":"Swagger Petstore","license":{"name":"MIT"}},"servers":[{"url":"http://petstore.swagger.io/v1"}],"paths":{"/pets":{"get":{"summary":"List all pets","operationId":"listPets","tags":["pets"],"parameters":[{"name":"limit","in":"query","description":"How many items to return at one time (max 100)","required":false,"schema":{"type":"integer","maximum":100,"format":"int32"}}],"responses":{"200":{"description":"A paged array of pets","headers":{"x-next":{"description":"A link to the next page of responses","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pets"}}}},"default":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a pet","operationId":"createPets","tags":["pets"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pet"}}},"required":true},"responses":{"201":{"description":"Null response"},"default":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pets/{petId}":{"get":{"summary":"Info for a specific pet","operationId":"showPetById","tags":["pets"],"parameters":[{"name":"petId","in":"path","required":true,"description":"The id of the pet to retrieve","schema":{"type":"string"}}],"responses":{"200":{"description":"Expected response to a valid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pet"}}}},"default":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Pet":{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"tag":{"type":"string"}}},"Pets":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/Pet"}},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"}}}}}} required: - contents required: - type - config IntegrationApiSpecProviderPayload: description: > API spec provider registered by a catalog integration. Integrations can function as API spec providers where they register a globally unique `type` and config schema which defines the shape of `config`. Consult integration documentation to learn more about available API spec providers. type: object required: - type - config - integration_instance properties: type: type: string description: The globally unique API spec provider type that is registered by a given catalog integration. minLength: 1 maxLength: 120 example: swaggerhub_api_version config: type: object additionalProperties: true minProperties: 1 description: JSON object containing values as defined by integration provider's config schema. example: owner: petco api: pet_store version: v3 integration_instance: type: string description: The integration instance id or name ResourceBoundIntegrationApiSpecProviderPayload: description: > API spec provider registered by a catalog integration. These providers differ from `IntegrationApiSpecProvider` in that they denote a binding relationship between a resource type and the API spec. This means that the API Spec will automatically be created/deleted for/from a service as resources of the given type are mapped/unmapped. Consult integration documentation to learn more about available API spec providers. type: object required: - type - config properties: type: type: string description: > The globally unique API spec provider type that is registered by a given catalog integration. Resource-bound providers create a 1-to-1 mapping between a resource type and the API Spec. minLength: 1 maxLength: 120 config: type: object required: - resource_id properties: resource_id: type: string description: ID of the associated Resource the API spec is bound to. example: IqkHvMdyHukxcwAs BaseError: type: object title: Error description: standard error required: - status - title - instance - detail properties: status: type: integer description: > The HTTP status code of the error. Useful when passing the response body to child properties in a frontend UI. Must be returned as an integer. readOnly: true title: type: string description: | A short, human-readable summary of the problem. It should not change between occurences of a problem, except for localization. Should be provided as "Sentence case" for direct use in the UI. readOnly: true type: type: string description: The error type. readOnly: true instance: type: string description: | Used to return the correlation ID back to the user, in the format kong:trace:. This helps us find the relevant logs when a customer reports an issue. readOnly: true detail: type: string description: > A human readable explanation specific to this occurence of the problem. This field may contain request/entity data to help the user understand what went wrong. Enclose variable values in square brackets. Should be provided as "Sentence case" for direct use in the UI. readOnly: true InvalidParameters: type: array nullable: false uniqueItems: true minItems: 1 description: invalid parameters items: oneOf: - $ref: "#/components/schemas/InvalidParameterStandard" - $ref: "#/components/schemas/InvalidParameterMinimumLength" - $ref: "#/components/schemas/InvalidParameterMaximumLength" - $ref: "#/components/schemas/InvalidParameterChoiceItem" - $ref: "#/components/schemas/InvalidParameterDependentItem" InvalidParameterStandard: type: object additionalProperties: false properties: field: type: string example: name readOnly: true rule: $ref: "#/components/schemas/InvalidRules" source: type: string example: body reason: type: string example: is a required field readOnly: true required: - field - reason InvalidParameterMinimumLength: type: object additionalProperties: false properties: field: type: string example: name readOnly: true rule: description: invalid parameters rules type: string readOnly: true nullable: false enum: - min_length - min_digits - min_lowercase - min_uppercase - min_symbols - min_items - min minimum: type: integer example: 8 source: type: string example: body reason: type: string example: must have at least 8 characters readOnly: true required: - field - reason - rule - minimum InvalidParameterMaximumLength: type: object additionalProperties: false properties: field: type: string example: name readOnly: true rule: description: invalid parameters rules type: string readOnly: true nullable: false enum: - max_length - max_items - max maximum: type: integer example: 8 source: type: string example: body reason: type: string example: must not have more than 8 characters readOnly: true required: - field - reason - rule - maximum InvalidParameterChoiceItem: type: object additionalProperties: false properties: field: type: string example: name readOnly: true rule: description: invalid parameters rules type: string readOnly: true nullable: false enum: - enum reason: type: string example: is a required field readOnly: true choices: type: array uniqueItems: true readOnly: true nullable: false minItems: 1 items: {} source: type: string example: body required: - field - reason - rule - choices InvalidParameterDependentItem: type: object additionalProperties: false properties: field: type: string example: name readOnly: true rule: description: invalid parameters rules type: string readOnly: true nullable: true enum: - dependent_fields reason: type: string example: is a required field readOnly: true dependents: type: array uniqueItems: true nullable: true items: {} readOnly: true source: type: string example: body required: - field - rule - reason - dependents InvalidRules: description: invalid parameters rules type: string readOnly: true nullable: true enum: - required - is_array - is_base64 - is_boolean - is_date_time - is_integer - is_null - is_number - is_object - is_string - is_uuid - is_fqdn - is_arn - unknown_property - missing_reference - is_label - matches_regex - invalid - is_supported_network_availability_zone_list - is_supported_network_cidr_block - is_supported_provider_region - type examples: PreviewServiceApiUrlPayload: value: provider: type: url config: url: https://my-company.com/api-specs/openapi.yaml PreviewServiceApiRawPayload: value: provider: type: raw config: contents: > openapi: 3.0.0 info: version: 1.0.0 title: Swagger Petstore license: name: MIT servers: - url: http://petstore.swagger.io/v1 paths: /pets: get: summary: List all pets operationId: listPets tags: - pets parameters: - name: limit in: query description: How many items to return at one time (max 100) required: false schema: type: integer maximum: 100 format: int32 responses: '200': description: A paged array of pets headers: x-next: description: A link to the next page of responses schema: type: string content: application/json: schema: $ref: '#/components/schemas/Pets' default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: summary: Create a pet operationId: createPets tags: - pets requestBody: content: application/json: schema: $ref: '#/components/schemas/Pet' required: true responses: '201': description: Null response default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /pets/{petId}: get: summary: Info for a specific pet operationId: showPetById tags: - pets parameters: - name: petId in: path required: true description: The id of the pet to retrieve schema: type: string responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: '#/components/schemas/Pet' default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Pet: type: object required: - id - name properties: id: type: integer format: int64 name: type: string tag: type: string Pets: type: array maxItems: 100 items: $ref: '#/components/schemas/Pet' Error: type: object required: - code - message properties: code: type: integer format: int32 message: type: string PreviewServiceApiIntegrationPayload: value: provider: type: github_repo integration_instance: bd24cfdd-619e-4696-b58d-a9ea49e5ea39 config: owner: MyOrganization repo: MyService spec_path: openapi.yaml PreviewServiceApiResourcePayload: value: provider: type: swaggerhub_api_version config: resource_id: ok-qTDpuiQp7DWK0 PreviewServiceApiResponseJson: value: openapi: 3.0.0 info: version: 1.0.0 title: Swagger Petstore license: name: MIT servers: - url: http://petstore.swagger.io/v1 paths: /pets: get: summary: List all pets operationId: listPets tags: - pets parameters: - name: limit in: query description: How many items to return at one time (max 100) required: false schema: type: integer maximum: 100 format: int32 responses: "200": description: A paged array of pets headers: x-next: description: A link to the next page of responses schema: type: string content: application/json: schema: ref: "#/components/schemas/Pets" default: description: unexpected error content: application/json: schema: ref: "#/components/schemas/Error" post: summary: Create a pet operationId: createPets tags: - pets requestBody: content: application/json: schema: ref: "#/components/schemas/Pet" required: true responses: "201": description: Null response default: description: unexpected error content: application/json: schema: ref: "#/components/schemas/Error" /pets/{petId}: get: summary: Info for a specific pet operationId: showPetById tags: - pets parameters: - name: petId in: path required: true description: The id of the pet to retrieve schema: type: string responses: "200": description: Expected response to a valid request content: application/json: schema: ref: "#/components/schemas/Pet" default: description: unexpected error content: application/json: schema: ref: "#/components/schemas/Error" components: schemas: Pet: type: object required: - id - name properties: id: type: integer format: int64 name: type: string tag: type: string Pets: type: array maxItems: 100 items: ref: "#/components/schemas/Pet" Error: type: object required: - code - message properties: code: type: integer format: int32 message: type: string PreviewServiceApiResponseYaml: value: | openapi: 3.0.0 info: version: 1.0.0 title: Swagger Petstore license: name: MIT servers: - url: http://petstore.swagger.io/v1 paths: /pets: get: summary: List all pets operationId: listPets tags: - pets parameters: - name: limit in: query description: How many items to return at one time (max 100) required: false schema: type: integer maximum: 100 format: int32 responses: "200": description: A paged array of pets headers: x-next: description: A link to the next page of responses schema: type: string content: application/json: schema: $ref: "#/components/schemas/Pets" default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" post: summary: Create a pet operationId: createPets tags: - pets requestBody: content: application/json: schema: $ref: "#/components/schemas/Pet" required: true responses: "201": description: Null response default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /pets/{petId}: get: summary: Info for a specific pet operationId: showPetById tags: - pets parameters: - name: petId in: path required: true description: The id of the pet to retrieve schema: type: string responses: "200": description: Expected response to a valid request content: application/json: schema: $ref: "#/components/schemas/Pet" default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" components: schemas: Pet: type: object required: - id - name properties: id: type: integer format: int64 name: type: string tag: type: string Pets: type: array maxItems: 100 items: $ref: "#/components/schemas/Pet" Error: type: object required: - code - message properties: code: type: integer format: int32 message: type: string UnauthorizedExample: value: status: 401 title: Unauthorized instance: kong:trace:8347343766220159418 detail: Unauthorized ForbiddenExample: value: status: 403 title: Forbidden instance: kong:trace:2723154947768991354 detail: You do not have permission to perform this action NotFoundExample: value: status: 404 title: Not Found instance: kong:trace:6816496025408232265 detail: Not Found securitySchemes: konnectAccessToken: type: http scheme: bearer bearerFormat: JWT description: > The Konnect access token is meant to be used by the Konnect dashboard and the decK CLI authenticate with. personalAccessToken: type: http scheme: bearer bearerFormat: Token description: > The personal access token is meant to be used as an alternative to basic-auth when accessing Konnect via APIs. You can generate a Personal Access Token (PAT) from the [personal access token page](https://cloud.konghq.com/global/account/tokens/) in the Konnect dashboard. The PAT token must be passed in the header of a request, for example: `curl -X GET 'https://global.api.konghq.com/v2/users/' --header 'Authorization: Bearer kpat_xgfT...'` systemAccountAccessToken: type: http scheme: bearer bearerFormat: Token description: > The system account access token is meant for automations and integrations that are not directly associated with a human identity. You can generate a system account Access Token by creating a system account and then obtaining a system account access token for that account. The access token must be passed in the header of a request, for example: `curl -X GET 'https://global.api.konghq.com/v2/users/' --header 'Authorization: Bearer spat_i2Ej...'` ```