Style Validator

Last modified on May 06, 2021

Note: This information applies to SwaggerHub On-Premise versions up to 1.19.1. In later versions, Style Validator was replaced with organization-level API Standardization.

Use Style Validator to check if your OpenAPI definition matches certain description standards. For example, your company’s guidelines may require that all the properties have examples specified. Style Validator helps you automate such checks.

When configuring Style Validator, you select the validation rules to apply to your API. Style Validator will check your OpenAPI definition according to these rules and notify you about any failed validations.

Configure Style Validator

Style Validator currently supports OpenAPI 2.0 definitions. To configure the Style Validator, you must be the API owner or a collaborator with the Editor role.

  1. Open your API page in SwaggerHub. If the API has several versions, select the version you want to validate:

    Selecting an API version
  2. Click the API name, switch to the Integrations tab, and click Add New Integrations:

    Add New Integration menu command
  3. Select Style Validator from the list of integrations.

  4. Select the validation rules to apply (see below).

  5. Specify other configuration options:

    • Name – an arbitrary display name for the Style Validator.

    • Update API with Style Validation comments – Specifies whether the Validator will insert comments before the lines that do not match the check settings.

    • Require API to pass Style Validation to be publishable – If this option is selected, you will be able to publish the API only if it passes all of the selected validations.

    • Enabled – Specifies if the Style Validator is enabled or disabled.

  6. Click Create and Execute.

Style Validator will run every time you save your API in the editor. If it finds issues, you will see an error message on the screen.

Supported validations

API Info

  • API title must be present and non-empty string

  • API description must be present and non-empty string

  • API license must be present and non-empty string

  • API contact must be present and non-empty string

Example of the info block that passes these validations:

swagger: '2.0'
info:
  title: Swagger Petstore
  description: This is a sample Petstore server.
  version: 1.0.0
  contact:
    email: apiteam@swagger.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

Operations

  • operationId must be present and non-empty string

    Note: operationId values must be unique within the API definition
  • Operation summary must be present and non-empty string

  • summary should start with upper case and end with a dot

  • Operation description must be present and non-empty string

  • Operation must have a tag and non-empty string

    Note: This rule allows one or more tags per operation
  • Operation must have one and only one tag

  • Operation must have at least one 2xx response

  • Operation must have a default response

Naming strategy

Enforce naming strategy for paths, parameters and property names:

  • underscore_case
  • camelCase

Models

  • Required property list must exist

    Note: The required list must contain at least one property. An empty required list is a syntax error in OpenAPI.
    definitions:
      Pet:
        type: object
        required:    # <-------
          - name
        properties:
          name:
            type: string
            example: doggie
          photoUrls:
            type: array
            items:
              type: string
  • All model properties must have examples

    definitions:
      User:
        type: object
        properties:
          id:
            type: integer
            format: int64
            example: 1    # <-------
          username:
            type: string
            example: bob  # <-------
  • API must not have local definitions (i.e. only $refs are allowed)

    Checking in-place definitions

    It is a good practice to place all data model definitions in the definitions section of your API and reference them by using $ref.

Run Style Validator

Style Validator runs automatically every time you save your API in the SwaggerHub editor.

You can also run it manually from the integrations list:

Running the Style Validator
Note: Syntax errors may prevent Style Valitator from fully analyzing your definition. We recommend that you fix all errors before running Style Validator.

Notifications

If Style Validator finds an issue, you will see an error indicator of the SwaggerHub Editor. Click the Integration Errors link to view the failed validations. In the error popup, click Detail to expand the list of failed validations and the problematic line numbers:

Viewing information on errors

Click the image to enlarge it.

Also, if Style Validator is configured with the Update API with Style Validation comments option, comments are added before the lines that failed the validations:

Comments on problematic lines in the OpenAPI definition

Click the image to enlarge it.

See Also

Integrations
API Standardization

Highlight search results