From 5db1c2f78ea797c5b6e521457602bcdea432a668 Mon Sep 17 00:00:00 2001 From: Robert Wallach Date: Thu, 8 Feb 2018 15:08:17 -0600 Subject: [PATCH] Update openapi-validation.md --- articles/modeling/openapi-validation.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/articles/modeling/openapi-validation.md b/articles/modeling/openapi-validation.md index 8a0c804..bf67bc1 100644 --- a/articles/modeling/openapi-validation.md +++ b/articles/modeling/openapi-validation.md @@ -2,11 +2,35 @@ ![](../../assets/gifs/file-validation-oas-spec.gif) +## What OpenAPI validation is the process of verifying the underlying OpenAPI file syntax by making sure it conforms to the [OpenAPI Specification requirements](https://github.com/OAI/OpenAPI-Specification#the-openapi-specification) provided by the [OpenAPI Initiative](https://www.openapis.org/). Stoplight immediately validates any changes done to a spec to ensure they are in the correct format prior to being saved. > Stoplight currently supports the OpenAPI v2 specification. We are working on support for OpenAPI v3, and should have more information in the coming months. +## Why +- Validation promotes data integrity in your data store. For example, a user making updates during a PUT operation might omit data for an important property and overwrite valid data, compromising data integrity. +- Validations indicates that you are engaging in good design practice and your API design is consistent. + +## Best Practices +- All requests made to an API should be validated before processing +- Mark all mandatory properties as **Required** to ensure that the value of the property is provided +- Assign a default value to optional properties or parameters with missing values. The server will use the default value when a value is missing or not provided +- You can use the keyword **ReadOnly** to designate a property that can be sent in a response and should not be sent in a request + + +> Using a default value is not recommended when a property or parameter is mandatory + +- An API can comsume different media types, the accepted media type can be specified using the **consume** keyword at the operational level or root level to define acceptable media types. For example: + +``` +consumes: +multipart/form-data +or +consumes: +application/json +``` +- An HTTP response containing a user friendly error description is useful when validation fails *** **Related**