REST Resource: projects.locations.apis.versions.specs

Resource: Spec

Represents a spec associated with an API version in the API Hub. Note that specs of various types can be uploaded, however parsing of details is supported for OpenAPI spec currently.

JSON representation 
{
  "name": string,
  "displayName": string,
  "specType": {
    object (AttributeValues)
  },
  "contents": {
    object (SpecContents)
  },
  "details": {
    object (SpecDetails)
  },
  "sourceUri": string,
  "createTime": string,
  "updateTime": string,
  "lintResponse": {
    object (LintResponse)
  },
  "attributes": {
    string: {
      object (AttributeValues)
    },
    ...
  },
  "documentation": {
    object (Documentation)
  },
  "parsingMode": enum (ParsingMode),
  "sourceMetadata": [
    {
      object (SourceMetadata)
    }
  ]
}
Fields
name

string

Identifier. The name of the spec.

Format: projects/{project}/locations/{location}/apis/{api}/versions/{version}/specs/{spec}
displayName

string

Required. The display name of the spec. This can contain the file name of the spec.
specType

object (AttributeValues)

Required. The type of spec. The value should be one of the allowed values defined for projects/{project}/locations/{location}/attributes/system-spec-type attribute. The number of values for this attribute will be based on the cardinality of the attribute. The same can be retrieved via GetAttribute API.

Note, this field is mandatory if content is provided.
contents

object (SpecContents)

Optional. Input only. The contents of the uploaded spec.
details

object (SpecDetails)

Output only. Details parsed from the spec.
sourceUri

string

Optional. The URI of the spec source in case file is uploaded from an external version control system.
createTime

string (Timestamp format)

Output only. The time at which the spec was created.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

Output only. The time at which the spec was last updated.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
lintResponse

object (LintResponse)

Optional. The lint response for the spec.
attributes

map (key: string, value: object (AttributeValues))

Optional. The list of user defined attributes associated with the spec. The key is the attribute name. It will be of the format: projects/{project}/locations/{location}/attributes/{attribute}. The value is the attribute values associated with the resource.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
documentation

object (Documentation)

Optional. The documentation of the spec. For OpenAPI spec, this will be populated from externalDocs in OpenAPI spec.
parsingMode

enum (ParsingMode)

Optional. Input only. Enum specifying the parsing mode for OpenAPI Specification (OAS) parsing.
sourceMetadata[]

object (SourceMetadata)

Output only. The list of sources and metadata from the sources of the spec.

SpecContents

The spec contents.

JSON representation 
{
  "contents": string,
  "mimeType": string
}
Fields
contents

string (bytes format)

Required. The contents of the spec.

A base64-encoded string.
mimeType

string

Required. The mime type of the content for example application/json, application/yaml, application/wsdl etc.

SpecDetails

SpecDetails contains the details parsed from supported spec types.

JSON representation 
{
  "description": string,

  // Union field details can be only one of the following:
  "openApiSpecDetails": {
    object (OpenApiSpecDetails)
  }
  // End of list of possible types for union field details.
}
Fields
description

string

Output only. The description of the spec.

Union field details.

details can be only one of the following:
openApiSpecDetails

object (OpenApiSpecDetails)

Output only. Additional details apart from OperationDetails parsed from an OpenAPI spec. The OperationDetails parsed from the spec can be obtained by using ListAPIOperations method.

OpenApiSpecDetails

OpenApiSpecDetails contains the details parsed from an OpenAPI spec in addition to the fields mentioned in SpecDetails.

JSON representation 
{
  "format": enum (Format),
  "version": string,
  "owner": {
    object (Owner)
  }
}
Fields
format

enum (Format)

Output only. The format of the spec.
version

string

Output only. The version in the spec. This maps to info.version in OpenAPI spec.
owner

object (Owner)

Output only. Owner details for the spec. This maps to info.contact in OpenAPI spec.

Format

Enumeration of spec formats.

Enums
FORMAT_UNSPECIFIED SpecFile type unspecified.
OPEN_API_SPEC_2_0 OpenAPI Spec v2.0.
OPEN_API_SPEC_3_0 OpenAPI Spec v3.0.
OPEN_API_SPEC_3_1 OpenAPI Spec v3.1.

LintResponse

LintResponse contains the response from the linter.

JSON representation 
{
  "issues": [
    {
      object (Issue)
    }
  ],
  "summary": [
    {
      object (SummaryEntry)
    }
  ],
  "state": enum (LintState),
  "source": string,
  "linter": enum (Linter),
  "createTime": string
}
Fields
issues[]

object (Issue)

Optional. Array of issues found in the analyzed document.
summary[]

object (SummaryEntry)

Optional. Summary of all issue types and counts for each severity level.
state

enum (LintState)

Required. Lint state represents success or failure for linting.
source

string

Required. Name of the linting application.
linter

enum (Linter)

Required. Name of the linter used.
createTime

string (Timestamp format)

Required. Timestamp when the linting response was generated.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

Issue

Issue contains the details of a single issue found by the linter.

JSON representation 
{
  "code": string,
  "path": [
    string
  ],
  "message": string,
  "severity": enum (Severity),
  "range": {
    object (Range)
  }
}
Fields
code

string

Required. Rule code unique to each rule defined in linter.
path[]

string

Required. An array of strings indicating the location in the analyzed document where the rule was triggered.
message

string

Required. Human-readable message describing the issue found by the linter.
severity

enum (Severity)

Required. Severity level of the rule violation.
range

object (Range)

Required. Object describing where in the file the issue was found.

Severity

Severity of the issue.

Enums
SEVERITY_UNSPECIFIED Severity unspecified.
SEVERITY_ERROR Severity error.
SEVERITY_WARNING Severity warning.
SEVERITY_INFO Severity info.
SEVERITY_HINT Severity hint.

Range

Object describing where in the file the issue was found.

JSON representation 
{
  "start": {
    object (Point)
  },
  "end": {
    object (Point)
  }
}
Fields
start

object (Point)

Required. Start of the issue.
end

object (Point)

Required. End of the issue.

Point

Point within the file (line and character).

JSON representation 
{
  "line": integer,
  "character": integer
}
Fields
line

integer

Required. Line number (zero-indexed).
character

integer

Required. Character position within the line (zero-indexed).

SummaryEntry

Count of issues with a given severity.

JSON representation 
{
  "severity": enum (Severity),
  "count": integer
}
Fields
severity

enum (Severity)

Required. Severity of the issue.
count

integer

Required. Count of issues with the given severity.

LintState

Lint state represents success or failure for linting.

Enums
LINT_STATE_UNSPECIFIED Lint state unspecified.
LINT_STATE_SUCCESS Linting was completed successfully.
LINT_STATE_ERROR Linting encountered errors.

Linter

Enumeration of linter types.

Enums
LINTER_UNSPECIFIED Linter type unspecified.
SPECTRAL Linter type spectral.
OTHER Linter type other.

ParsingMode

Specifies the parsing mode for API specifications during creation and update. - RELAXED: Parsing errors in the specification content do not fail the API call. - STRICT: Parsing errors in the specification content result in failure of the API call. If not specified, defaults to RELAXED.

Enums
PARSING_MODE_UNSPECIFIED Defaults to RELAXED.
RELAXED Parsing of the Spec on create and update is relaxed, meaning that parsing errors the spec contents will not fail the API call.
STRICT Parsing of the Spec on create and update is strict, meaning that parsing errors in the spec contents will fail the API call.

Methods

create

 Add a spec to an API version in the API hub.

delete

 Delete a spec.

get

 Get details about the information parsed from a spec.

getContents

 Get spec contents.

lint

 Lints the requested spec and updates the corresponding API Spec with the lint response.

list

 List specs corresponding to a particular API resource.

patch

 Update spec.