QID 570048

QID 570048: REUSE-Missing Examples in Swagger File in Open API 2.0

Examples are really important. When defining an OpenAPI specification, ensure every definition, operation request and response have examples. Analyzing the swagger file resulted in examples missing on some elements.

It is not mandatory to have examples. Examples help API users to ensure they are making best use of functionality. If example is missing in one of the following elements this warning will be reported:

Operation Requests
Operation Responses
Operation Parameters
Global Components
Global Parameters
Example Schema Check
Use of value/externalValue

Solution

Add examples to all elements. For example:

paths: /users: post: operationId: createUser tags: - "Users" summary: Create a new user description: A new user account. requestBody: description: Give us the new user name content: application/json: schema: $ref: '#/components/schemas/User' examples: TemporaryUser: summary: User will be on the system for a short period of time. value: name: UserName1 ActiveYears: 3 PermanantUser: summary: User will be on the system indefinitely value: name: UserName2 ActiveYears: 100 responses: "200": description: User account created active for requested years content: application/json: schema: $ref: '#/components/schemas/User' examples: TemporaryUser: summary: Temporary user Created with information provided. value: name: UserName1 ActiveYears:2 PermanantUser: summary: Permanant user for life time created using information provided. value: name: UserName2 ActiveYears: 100

Vendor References

CVEs related to QID 570048

Software Advisories

Advisory ID	Software	Component	Link

By selecting these links, you may be leaving CVEreport webspace. We have provided these links to other websites because they may have information that would be of interest to you. No inferences should be drawn on account of other sites being referenced, or not, from this page. There may be other websites that are more appropriate for your purpose. CVEreport does not necessarily endorse the views expressed, or concur with the facts presented on these sites. Further, CVEreport does not endorse any commercial products that may be mentioned on these sites. Please address comments about any linked pages to [email protected].