Create a 'Best Practices' wiki page

[webron]

See: https://groups.google.com/d/msg/swagger-workgroup/PaAX10gFYFM/qdZVyP5n9tkJ

[webron]

This is something to take into account for he next version of the spec.

[drewish]

Yeah a how to write your API so it's compatible with swagger guide would be helpful. You could point the people who get frustrated trying to document existing APIs there so they'd know what they need to change in their next version to be able to use Swagger.

[webron]

As long as we replace Swagger with OpenAPI there, sure ;)

@drewish - it would be very useful if you could cover some pitfalls you encountered in your process. Knowing the spec, it's difficult to realize where those pain points may be, and we'd definitely want to cover those.

[earth2marsh]

👍

[webron]

Parent issue: #589

[KiaraGrouwstra]

I hope using schema (and therefore $refs) in non-body parameters could be encouraged for 3.0, since this new option seems non-obvious to those upgrading, while it could e.g. enable generated docs to cross-link parameters with models used in responses.

[RobDolinMS]

@webron Would you mind if I moved this out to milestone==v3.Next (i.e. after v3.0.0)?
P.S. If anyone interested in this (@drewish @earth2marsh @tycho01) wants to just go ahead and start the wiki page, that would be good ness too.

[webron]

@RobDolinMS - I don't recall what v3.Next is. This is part of the documentation of 3.0.0 but it can come after the official release of it. It's not a post 3.0.0 feature.

[handrews]

In the intervening years we closed the wiki and created learn.openapis.org. If there's more work to do on this, please open issues on the OAI/learn.openapis.org repository.