Add guide on validating api specifications

general-guidelines/validating-api-descriptions.md

@@ -0,0 +1,74 @@
+# Validating API Description
+
+API description files (e.g. OpenAPI specification for REST APIs) SHOULD be validated to verify whether they comply with this guidelines. In order to do that you can utilize [Spectral](https://github.com/stoplightio/spectral) ruleset implementing them.
+
+## Installing Spectral
+
+To install Spectral you will need Node.js and a package manager (npm or yarn).
+
+```
+npm install -g @stoplight/spectral
+
+# OR
+
+yarn global add @stoplight/spectral
+```
+
+### Docker
+
+Spectral is also available as a Docker image, which can be handy for all sorts of things, like if you're contributing code to Spectral, want to integrate it into your CI build.
+
+```
+docker run --rm -it stoplight/spectral lint "${url}"
+```
+
+If the file you want to lint is on your computer, you'll need to mount the directory where the file resides as a volume
+
+```
+docker run --rm -it -v $(pwd):/tmp stoplight/spectral lint "/tmp/file.yaml"
+```
+
+## Using Spectral
+
+Once installed Spectral you can validate any `YAML` or `JSON` file according to a given set of rules. Spectral has a predefined set of rules validating OpenAPI 2.x (Swagger) and OpenAPI 3.x files.
+
+Spectral comes with a CLI and can be run from your command line:
+
+```
+spectral lint MY_SPEC_FILE.yaml
+```
+
+For more details about how to utilize Spectral CLI you can check the CLI built-in help:
+
+```
+spectral lint -h
+```
+
+or go to the official [Spectral documentation](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/guides/cli.md).
+
+Spectral can also be used from within Javascript. For details on how to accomplish this, please refer to the [documentation](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/guides/javascript.md).
+
+## Validating with Adidas API Guidelines
+
+To check whether your API Specification complies with Adidas API Guidelines copy the `.spectral` file from this repository ([here](https://github.com/adidas/api-guidelines/blob/master/.spectral.yml)).
+
+Once it is in the same directory as the one from which you are calling spectral it will be used automatically.
+
+``` 
+spectral lint my-api-spec.yaml
+```
+
+### Validation problems
+
+Spectral defines 4 levels of problem severity:
+
+1. error - the specification either does not pass standard YAML/JSON structure validation, standard OAS2/OAS3 validation or is not compliant with core adidas guidelines.
+2. warning - the specification lacks certain important validation check (e.g. `hosts` for OAS2) which are not required, but you should be cautious about them.
+3. information - there are some best practices which you did not implement in your specification and should consider doing so.
+4. hint - you should be aware that there are some additional best practices which you can consider implementing in your specification.
+
+Currently any problem of severity of error or warning will cause a failure status code of `1`. This means that any `error` or `warning` in your specification will prevent your CI/CD pipeline from succeeding. During design process you may want to ignore certain warnings, such as the runtime information (e.g. `hosts` or `servers`). In order to do that you can add a `--skip-rule` flag:
+
+```
+spectral lint my-api-spec.yaml --skip-rule=protocol-https-only-oas3
+```