That, for the time being, is a trade-off I’m willing to make. $ref: './openapi.yml#/components/schemas/user-collection'Īdmittedly this fragments the API definition and makes it substantially more difficult to use any existing API spec editors and UI’s. $ref: './openapi.yaml#/components/parameters/filters' Alas, the JSONPath notation for JSON References is… unpleasant on the eye, it is clearly defined and I’ve certainly seen worse syntax in other places in tech.Įndpoints can now clearly be defined as a sort of map between the URI, verb and resources. The root of my OpenAPI spec now becomes a sort of index for all the endpoints in my API which is a lot nicer and easier to manage. $ref: "endpoints/user.yml#/paths/~1user~1" That means you can achieve the following API spec. Speccy has a wonderful little feature that resolves external references between files. For disambiguation sake, some people consider operations and endpoints to be the same “thing” though for the purposes of this example I would disagree. Yet, OpenAPI has no concept of an endpoint. To follow the library example, there would be a “user” endpoint, a “book” endpoint” and a “loan” endpoint. Logical endpoint groupingsĪs APIs grow, I start to group operations into logical endpoints where all operations share a given resource or domain process. In my view, hundreds of lines of YAML isn’t very maintainable. A simple library API with users books and loans could be almost 20 operations and hundreds of lines of YAML.
While it is possible to define the response inline, its generally considered best practice to define resources once and then $ref-erence them.įor example sake, lets assume that a resource is addressed via its /resource and /resource/:id URIs and has full HTTP verb support accordingly:įor an API of just a handful of simple resources, the full API spec could grow long and unwieldy very very quickly. For example, take this simple API definition for a user. In the OpenAPI v3 spec, the combination of all three of these is better known as an “operation” and is defined in a similarly hierarchical fashion.