Validate API specifications

This page applies to Apigee and Apigee hybrid.

API hub provides an in-built Spectral linter (validator) which validates your API's OpenAPI specification. Soon after you add an OpenAPI specification to your API version, the validator (which is enabled by default) validates the specification, and reports the findings in the Google Cloud console.

Disable specification validation

By default, the linter is enabled. To disable the linter, in the Google Cloud console, go to the API hub > Settings > Actions page, and then in the Linting section, disable the Linting option.

Style guide

A style guide is a set of rules against which API hub validates an OpenAPI specification. API hub uses a default style guide for validating the OpenAPI specifications. For the default style guide rules, see OpenAPI Rules.

Upload a new style guide

Console

To upload a new style guide, do the following steps:

  1. Create a new style by extending the default style guide. For more information, see Create a ruleset.

  2. In the Google Cloud console, go to the API hub > Settings > Actions page.

  3. In the Linting section, click Upload new style document.
  4. Upload the new style document (created in step 1), and then click Save.

REST API

To upload a new style guide for linting, issue a PATCH request to the following API:

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/plugins/standard-linter/styleGuide?update_mask=contents

For more information about the API, see UpdateStyleGuide.

The following example shows the API call to upload a style guide.

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"name":"projects/test-project-1/locations/us-central1/plugins/standard-linter/styleGuide",
"contents":{  "contents": "ZXh0ZW5kczogWyJzcGVjdHJhbDpvYXMiXQo=",
  "mimeType": "text/yaml"}}' \ 
-X PATCH \
https://apihub.googleapis.com/v1/projects/test-project-1/locations/us-central1/plugins/standard-linter/styleGuide?update_mask=contents

Download the default style guide

To download the default style guide used by API hub for linting, do the following steps:

  1. In the Google Cloud console, go to the API hub > Settings > Actions page.

  2. In the Linting section, click Download default style document. This downloads the default style document to your local system.

Download the latest style guide

Console

To download the style guide that is currently used by API hub for linting, do the following steps:

  1. In the Google Cloud console, go to the API hub > Settings > Actions page.

  2. In the Linting section, click Download latest style document. This downloads the default style document to your local system.

REST API

To download the style guide that is currently used by API hub for linting, issue a GET request to the following API:

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/plugins/standard-linter/styleGuide:contents

For more information about the API, see GetStyleGuide.

The following example shows the API call to download the current style guide.

curl -X \
GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  https://apihub.googleapis.com/v1/projects/test-project-1/locations/us-central1/plugins/standard-linter/styleGuide:contents

Limitations

The following limitations apply when creating and uploading custom style guides:

  • No URLs in extends property: Style guides can't contain URLs. Ensure that you don't include any URLs in the extends property of your ruleset when creating and uploading a style guide. For example, the following property construction might cause the upload to fail: extends: [spectral:oas", "https://mystyle.com/"].
  • functionsDir not allowed: The functionsDir property is not allowed in custom style guides. Spectral style guides with JavaScript will not be executed by API hub during the linting process.

    As a workaround, if you require the use of a custom style guide with JavaScript functions, perform the following steps:

    1. Run Spectral outside of API hub using your custom style guide.
    2. Update the linting results in the Lint attribute of the specification file in API hub.