Validate API specs with OpenAPI Style Validator

The OpenAPI Style Validator is a tool that helps developers create API specifications with understandable descriptions, examples and the use of naming conventions. The tool can be used as a library in Java code or in a CI/CD pipeline using a Maven or Gradle plugin.

GitHub Repo: https://github.com/claudioaltamura/openapi-style-validator-example

Transcript

1. VALIDATE API SPECS WITH OPENAPI STYLE VALIDATOR claudioaltamura
2. CLAUDIO ALTAMURA Hello, I’m Claudio I love building things | Software Developer claudioaltamura
3. 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
4. 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
5. info operation model naming conventions 03 WHAT CAN BE CHECKED? https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore-expanded.json
6. 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/..." } }
7. 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", ... } } }
8. 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" }, ... } ...
9. header path parameter properties 07 NAMING CONVENTIONS https://github.com/OpenAPITools/openapi-style-validator X-Store-Header /pets /pets/{id} pet-id
10. Parameter CamelCase PascalCase HyphenUpperCase HyphenCase UnderscoreCase UnderscoreUpperCase 08 NAMING CONVENTION EXAMPLE petId PetId Pet-Id pet-id pet_id PET_ID
11. mvn and gradle configuration 09 HOW CAN I USE THE TOOL?
12. 10 MVN mvn openapi-style-validator:validate <plugins> <plugin> <groupId>org.openapitools.openapistylevalidator</groupId> <artifactId>openapi-style-validator-maven-plugin</artifactId> <version>1.11</version> <configuration> <inputFile>petstore-expanded.json</inputFile> ... </configuration> </plugin> </plugins> https://github.com/OpenAPITools/openapi-style-validator?tab=readme-ov-file#releases-on-maven-central
13. <validateInfo*/> <validateOperation*/> <validateModel*/> <*Convention/> 11 CONFIGURATIONS https://github.com/OpenAPITools/openapi-style-validator?tab=readme-ov-file#options-file
14. 12 DEMO https://github.com/claudioaltamura/openapi-style-validator-example
15. Why do we need API Guidelines? Examples adidas Zalando 13 API GUIDELINES
16. 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 ... <pathNamingConvention>HyphenCase</pathNam <headerNamingConvention>HyphenUpperCase</ <parameterNamingConvention>CamelCase</par <propertyNamingConvention>CamelCase</prop ...
17. 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 ... <pathNamingConvention>HyphenCase</pathNam <headerNamingConvention>HyphenUpperCase</ <parameterNamingConvention>UnderscoreCase <propertyNamingConvention>UnderscoreCase< ... https://opensource.zalando.com/restful-api-guidelines
18. 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
19. claudioaltamura