Some suggestions for Swagger Implementation docs

[DanielMiller-agile6]

Description

While working on a ticket to implement Swagger docs for a new endpoint, I ran into a few issues that could be good to document somewhere. Figured I'd jot them down here in case they seem helpful.

• new swagger doc files need an entry added to .github/CODEOWNERS
• all new/edited endpoint docs in swagger need corresponding tests added to spec/requests/swagger_spec.rb
• "nullable" properties in our schemas don't appear to support the "nullable" or "x-nullable" options defined in rswag docs. using an array of types seems to work (e.g. property :detail, type: [:string, 'null'])
• "nullable" enum types should use the above "array" type method, but also needs to add nil to enumerated list of values (e.g. enum: [nil, 'pending', ... ])

Relevant URLs

Ticket: https://github.com/department-of-veterans-affairs/vets-api/pull/18460

VADocs p:age: https://depo-platform-documentation.scrollhelp.site/developer-docs/swagger-implementation

rswag docs: https://github.com/rswag/rswag

Which type of team are you on? (Platform team, VFS team, or Leadership)

VFS team (MyVA)

[jknipes]

Hi @DanielMiller-agile6 , thanks for your content suggestions. The Platform Content team will review your request and put it in our backlog to refine for next steps.