github.com/thetreep/go-swagger@v0.0.0-20240223100711-35af64f14f01/docs/usage/validate.md (about)

     1  # Validate a swagger spec
     2  
     3  The toolkit has a command to validate swagger specifications for you.
     4  It includes a full json-schema validator and adds some extra validations to ensure the spec is valid.
     5  
     6  ### Usage
     7  
     8  To validate a specification:
     9  
    10  ```
    11  Usage:
    12    swagger [OPTIONS] validate [validate-OPTIONS]
    13  
    14  validate the provided swagger document against a swagger spec
    15  
    16  Application Options:
    17    -q, --quiet                 silence logs
    18        --output=LOG-FILE       redirect logs to file
    19  
    20  Help Options:
    21    -h, --help                  Show this help message
    22  
    23  [validate command options]
    24            --skip-warnings     when present will not show up warnings upon validation
    25            --stop-on-error     when present will not continue validation after critical errors are found
    26  ```
    27  
    28  ### Swagger 2.0 resources
    29  
    30  * Specification Documentation: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md
    31  * JSON Schema: https://github.com/swagger-api/swagger-spec/blob/master/schemas/v2.0/schema.json
    32  
    33  ### Semantic Validation
    34  
    35  All the rules the validator tool supports:
    36  
    37  *	validate against jsonschema
    38  *	validate extra rules, inspired from [the sway swagger validator](https://github.com/apigee-127/sway/tree/master/docs#semantic-validation)
    39  
    40  Rule | Severity
    41  -----|---------
    42  definition can't declare a property that's already defined by one of its ancestors  | Error
    43  definition's ancestor can't be a descendant of the same model  | Error
    44  each api path should be non-verbatim (account for path param names) unique per method  | Error
    45  each path parameter should correspond to a parameter placeholder and vice versa  | Error
    46  path parameter declarations do not allow empty names _(`/path/{}` is not valid)_  | Error
    47  each definition property listed in the required array must be defined in the properties of the model  | Error
    48  each parameter should have a unique `name` and `in` combination  | Error
    49  each operation should have at most 1 parameter of type body  | Error
    50  each operation cannot have both a body parameter and a formData parameter  | Error
    51  each operation must have an unique `operationId`  | Error
    52  each reference must point to a valid object  | Error
    53  every default value that is specified must validate against the schema for that property  | Error
    54  items property is required for all schemas/definitions of type `array`  | Error
    55  param in path must have the property required: true
    56  every example that is specified should validate against the schema for that property  | Warning
    57  $ref should not have siblings  | Warning
    58  each referable definition must have references  | Warning