[FEEDBACK] - SWAGGER documentation as standard

[f3derical]

Summary

How about adopting SWAGGER as the standard developer documentation for APIs?

Link to standards item

https://apistandards.digital.health.nz/draft/api-publishing/Components

Which area of the standards does this apply to?

• [ ] Part A - API Concepts
• [ ] Part B - API Security
• [X] Part C - API Design and Development
• [ ] Part D - FHIR
• [ ] Community guidelines

[kyle-mwnz]

Hi @f3derical, thank you for the feedback across the 4 issues you have raised.

The OpenAPI specification, (which was formerly known as Swagger), is covered in the below pages as the favoured interface specification language to be used as part of a specification driven API design approach. Alongside this, the publishing standards offers specific guidance on required fields in an OpenAPI specification.

The overall guidance suggests that the interface is documented using OpenAPI, but should be published alongside other developer documentation such as code snippets, SDKs, and descriptions of the business context so a developer gets an understanding of the wider solution.

Does the existing content cover your feedback, or was there a further suggestion?

[f3derical]

That's great! Thanks for the clarifications