Validate API specs with OpenAPI Style Validator

Slide 1

Slide 1 text

VALIDATE API SPECS WITH OPENAPI STYLE VALIDATOR claudioaltamura

Slide 2

Slide 2 text

CLAUDIO ALTAMURA Hello, I’m Claudio I love building things | Software Developer claudioaltamura

Slide 3

Slide 3 text

Poorly readable and not understandable No documentation explaining how to use the API Changes are complicated and time consuming Inconsistent structures lead to confusion and errors 01 THE PROBLEM

Slide 4

Slide 4 text

OpenAPI Style Validator helps identify weaknesses in your API specs leading to consistent and understandable APIs API guidelines can be checked and enforced 02 THE SOLUTION https://github.com/OpenAPITools/openapi-style-validator

Slide 5

Slide 5 text

info operation model naming conventions 03 WHAT CAN BE CHECKED? https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore-expanded.json

Slide 6

Slide 6 text

04 INFO https://swagger.io/specification/#info-object "info": { "description": "A sample API that uses a petstore...", "contact": { "name": "Swagger API Team", "email": "apiteam@swagger.io", "url": "http://swagger.io" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/..." } }

Slide 7

Slide 7 text

05 OPERATION "paths": { "/pets": { "get": { "summary": "Returns all pets from the system...", "description": "**markdown** as representation...", "operationId": "findPets", "tags": ["pets"], ... } } } https://swagger.io/specification/#operation-object "paths": { "/pets": { "get": { "description": "Retrieves a comprehensive list...", "operationId": "findPets", ... } } }

Slide 8

Slide 8 text

06 MODEL https://swagger.io/specification/#schema-object "NewPet": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "pet’s name as it’s called", "example": "Garfield", }, ... "NewPet": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, ... } ...

Slide 9

Slide 9 text

header path parameter properties 07 NAMING CONVENTIONS https://github.com/OpenAPITools/openapi-style-validator X-Store-Header /pets /pets/{id} pet-id

Slide 10

Slide 10 text

Parameter CamelCase PascalCase HyphenUpperCase HyphenCase UnderscoreCase UnderscoreUpperCase 08 NAMING CONVENTION EXAMPLE petId PetId Pet-Id pet-id pet_id PET_ID

Slide 11

Slide 11 text

mvn and gradle configuration 09 HOW CAN I USE THE TOOL?

Slide 12

Slide 12 text

10 MVN mvn openapi-style-validator:validate org.openapitools.openapistylevalidator openapi-style-validator-maven-plugin 1.11 petstore-expanded.json ... https://github.com/OpenAPITools/openapi-style-validator?tab=readme-ov-file#releases-on-maven-central

Slide 13

Slide 13 text

<*Convention/> 11 CONFIGURATIONS https://github.com/OpenAPITools/openapi-style-validator?tab=readme-ov-file#options-file

Slide 14

Slide 14 text

12 DEMO https://github.com/claudioaltamura/openapi-style-validator-example

Slide 15

Slide 15 text

Why do we need API Guidelines? Examples adidas Zalando 13 API GUIDELINES

Slide 16

Slide 16 text

naming convention Path kebab-case /pet-orders Header Hyphenated Pascal-Case Order-Metadata Parameter camelCase customerNumber Property camelCase modifiedAt 14 ADIDAS https://adidas.gitbook.io/api-guidelines/rest-api-guidelines/rest ... HyphenCaseHyphenUpperCase CamelCaseCamelCase

Slide 17

Slide 17 text

naming convention Path kebab-case /pet-orders Header kebab-case with uppercase If-Modifed-Since Parameter snake_case customer_number Property snake_case modified_at 15 ZALANDO ... HyphenCaseHyphenUpperCase UnderscoreCase UnderscoreCase< ... https://opensource.zalando.com/restful-api-guidelines

Slide 18

Slide 18 text

helps to create consistent and understandable APIs assists in implementing API guidelines OpenAPI Style Validator is a small, but powerful tool not everything can be checked 16 CONCLUSION

Slide 19

Slide 19 text

claudioaltamura