Add note about empty fields and null values for API responses

Add a note the global swagger docs about some fields not showing up in responses as they are set to omitempty. Also add a note about null values for complicated field types that swagger-go has a hard time with. [NO TESTS NEEDED] Signed-off-by: Urvashi Mohnani <[email protected]>
containers · Oct 1, 2021 · 4ea5d69 · 4ea5d69
1 parent c6a896b
commit 4ea5d69
Showing 1 changed file with 9 additions and 0 deletions.
diff --git a/pkg/api/server/docs.go b/pkg/api/server/docs.go
@@ -15,6 +15,15 @@
 // NOTE: if you install the package podman-docker, it will create a symbolic
 // link for /run/docker.sock to /run/podman/podman.sock
 //
+// NOTE: some fields in the API response JSON are set as omitempty, which means that
+// if there is no value set for them, they will not show up in the API response. This
+// is a feature to help reduce the size of the JSON responses returned via the API.
+//
+// NOTE: due to the limitations of [go-swagger](https://github.com/go-swagger/go-swagger),
+// some field values that have a complex type show up as null in the docs as well as in the
+// API responses. This is because the zero value for the field type is null. The field
+// description in the docs will state what type the field is expected to be for such cases.
+//
 // See podman-service(1) for more information.
 //
 //  Quick Examples: