Serge Bazanski | cc25bdf | 2018-10-25 14:02:58 +0200 | [diff] [blame^] | 1 | // Copyright 2015 go-swagger maintainers |
| 2 | // |
| 3 | // Licensed under the Apache License, Version 2.0 (the "License"); |
| 4 | // you may not use this file except in compliance with the License. |
| 5 | // You may obtain a copy of the License at |
| 6 | // |
| 7 | // http://www.apache.org/licenses/LICENSE-2.0 |
| 8 | // |
| 9 | // Unless required by applicable law or agreed to in writing, software |
| 10 | // distributed under the License is distributed on an "AS IS" BASIS, |
| 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 12 | // See the License for the specific language governing permissions and |
| 13 | // limitations under the License. |
| 14 | |
| 15 | /* |
| 16 | Package validate provides methods to validate a swagger specification, |
| 17 | as well as tools to validate data against their schema. |
| 18 | |
| 19 | This package follows Swagger 2.0. specification (aka OpenAPI 2.0). Reference |
| 20 | can be found here: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md. |
| 21 | |
| 22 | Validating a specification |
| 23 | |
| 24 | Validates a spec document (from JSON or YAML) against the JSON schema for swagger, |
| 25 | then checks a number of extra rules that can't be expressed in JSON schema. |
| 26 | |
| 27 | Entry points: |
| 28 | - Spec() |
| 29 | - NewSpecValidator() |
| 30 | - SpecValidator.Validate() |
| 31 | |
| 32 | Reported as errors: |
| 33 | [x] definition can't declare a property that's already defined by one of its ancestors |
| 34 | [x] definition's ancestor can't be a descendant of the same model |
| 35 | [x] path uniqueness: each api path should be non-verbatim (account for path param names) unique per method |
| 36 | [x] each security reference should contain only unique scopes |
| 37 | [x] each security scope in a security definition should be unique |
| 38 | [x] parameters in path must be unique |
| 39 | [x] each path parameter must correspond to a parameter placeholder and vice versa |
| 40 | [x] each referenceable definition must have references |
| 41 | [x] each definition property listed in the required array must be defined in the properties of the model |
| 42 | [x] each parameter should have a unique `name` and `type` combination |
| 43 | [x] each operation should have only 1 parameter of type body |
| 44 | [x] each reference must point to a valid object |
| 45 | [x] every default value that is specified must validate against the schema for that property |
| 46 | [x] items property is required for all schemas/definitions of type `array` |
| 47 | [x] path parameters must be declared a required |
| 48 | [x] headers must not contain $ref |
| 49 | [x] schema and property examples provided must validate against their respective object's schema |
| 50 | [x] examples provided must validate their schema |
| 51 | |
| 52 | Reported as warnings: |
| 53 | [x] path parameters should not contain any of [{,},\w] |
| 54 | [x] empty path |
| 55 | [x] unused definitions |
| 56 | [x] unsupported validation of examples on non-JSON media types |
| 57 | [x] examples in response without schema |
| 58 | [x] readOnly properties should not be required |
| 59 | |
| 60 | Validating a schema |
| 61 | |
| 62 | The schema validation toolkit validates data against JSON-schema-draft 04 schema. |
| 63 | |
| 64 | It is tested against the full json-schema-testing-suite (https://github.com/json-schema-org/JSON-Schema-Test-Suite), |
| 65 | except for the optional part (bignum, ECMA regexp, ...). |
| 66 | |
| 67 | It supports the complete JSON-schema vocabulary, including keywords not supported by Swagger (e.g. additionalItems, ...) |
| 68 | |
| 69 | Entry points: |
| 70 | - AgainstSchema() |
| 71 | - ... |
| 72 | |
| 73 | Known limitations |
| 74 | |
| 75 | With the current version of this package, the following aspects of swagger are not yet supported: |
| 76 | [ ] errors and warnings are not reported with key/line number in spec |
| 77 | [ ] default values and examples on responses only support application/json producer type |
| 78 | [ ] invalid numeric constraints (such as Minimum, etc..) are not checked except for default and example values |
| 79 | [ ] rules for collectionFormat are not implemented |
| 80 | [ ] no validation rule for polymorphism support (discriminator) [not done here] |
| 81 | [ ] valid js ECMA regexp not supported by Go regexp engine are considered invalid |
| 82 | [ ] arbitrary large numbers are not supported: max is math.MaxFloat64 |
| 83 | |
| 84 | */ |
| 85 | package validate |