Style Validator

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: [email protected]
  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

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

See Also

In this section:
© 2024
Publication date: