Validate API specifications

This page applies to Apigee and Apigee hybrid.

Preview — Apigee API hub linting feature

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

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.

Note: In this topic, the terms linting and validating are used interchangeably. Both these terms mean the same.

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.

Note: To add your own custom rules, you must create a new style guide that extends the default style guide. After adding your custom rules in the new style guide, you must upload the new style guide in API hub.

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.
   Note: A validation step performed on the upload throws an error if a URL appears in the extends property of your ruleset. For example, this is an illegal property construction and will cause the upload to fail: extends: [spectral:oas", "https://mystyle.com/"].

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.

Note: A validation step performed on the upload throws an error if a URL appears in the extends property of your ruleset. For example, this is an illegal property construction and will cause the upload to fail: extends: [spectral:oas", "https://mystyle.com/"].

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