Named schema support in Swagger & OpenAPI for Spec

[opqdonut]

Currently, all spec schemas are inlined at the use site when generating Swagger & OpenAPI docs.

It would be nice to generate Swagger :definitions and OpenAPI :components :schemas like we do for Malli refs/vars. See #673 .

For Malli, it's easy to control what gets a named schema by using the schema structure. What do we want for spec? A named schema for each s/def?

[eval-on-point]

I was looking for this feature last week and asked about it in the Clojurians Slack. My team's main particular use case is to have spec coercion using OpenAPI's schema objects. Using the objects in the schema is useful because Swagger UI generates links from each route's parameters to the item in the schema.

That being said, I could see this use case being resolved in two ways:

1. Reitit uses metadata attached in Spec Records to determine which specs receive a named schema. Perhaps any Spec Record with the :openapi/title key gets a named schema with that key's value. If the value is true, then the Spec Record's name is used to avoid writing the same string in the :name key and :openapi/title key. There could maybe be a way to disable a particular named schema's generation in the :openapi map. This would support the case case where Spec Record A is used in OpenAPI Documents B and C, but the user only wants A's schema object to be generated in B.
2. The user manually populates the :components :schema/:definitions map with "spec-title" ::spec-name kvs. Then, reitit can dynamically create links from the route data to the schema objects when generating the OpenAPI/Swagger document.

Solution 1. has the advantage that it behaves more similarly to the feature that is already implemented for Malli. However, I only have passing familiarity with OpenAPI, Swagger, Swagger UI, reitit, etc. so take these ideas with caution.