OpenAPI

Gotchas

1. Be careful when using default values for parameters.
2. If the request payload doesn’t have a value for this parameter, OpenAPI will create an object and then insert this key-value pair in the object.
3. If the existence (or non-existence) of that object drives some business logic in your application, this will lead to unwanted behavior.
4. So, if you need to default values for parameters, look to see if it makes more sense to do the defaulting inside the application instead of doing it using the OpenAPI spec file.

Some great tips and tools to work with Open API

1. https://openapi.tools/
2. https://openapi.tools/#gui-editors

OpenAPI spec editing tools

Swagger YAML editing tool :

1. http://editor.swagger.io/
2. https://editor-next.swagger.io/

We can use this to generate server code and client code as well.

Stoplight studio is another good one.

OpenAPI CICD automated validation tools

42crunch.com

Redocly

1. Helps combine several smaller yaml files into one big final specification file.
2. Helps to generate a html file from the yaml specification file.
   1. The static file can then be served (e.g. in go applications) from an endpoint.

How to create OpenAPI schema definitions from scratch

1. Convert sample json to jsonSchema using https://transform.tools/
   1. As we modify the json, the jsonSchema will be updated
2. Convert jsonSchema to openAPI schema usint https://transform.tools/
   1. As we modify the jsonSchema, the openAPI schema will be updated
3. Convert openAPI schema from json to yaml format using json to yaml converters online
   1. e.g. https://jsonformatter.org/json-to-yaml

Generate server code from OpenAPI specification file

Reference

1. https://swagger.io/specification/
2. https://www.baeldung.com/swagger-format-descriptions

Tags

1. Contract first approach to API development
2. Formdata in OpenAPI specification file