Generate definition for different versions

[hpatoio]

I've a pretty big API definition. As you can imagine we have more versions and I must maintain more OS files.

So, for example, let's say I've version 1 and version 2.

Version 1 is like

/*
 * @oas [get] /pet/{petId}
 * description: "Returns all pets from the system that the user has access to"
 * parameters:
 *   - (path) petId=hi* {String} The pet ID
 *   - (query) limit {Integer:int32} The number of resources to return
 *   - (query) sort_by {String} The field to sort by
*/

In version 2 we REMOVE sort_by parameter and ADD size. So definition looks like:

/*
 * @oas [get] /pet/{petId}
 * description: "Returns all pets from the system that the user has access to"
 * parameters:
 *   - (path) petId=hi* {String} The pet ID
 *   - (query) limit {Integer:int32} The number of resources to return
 *   - (query) size {String} Size of the pet to filter by
*/

I would like to have the possibility to pass the version to AOS so that I can generate more OA definitions. So for version 1 I've have petId - limit - sort_by and size (because I want size to be available also for version 1) while for version 2 have petId - limit and size

I'm thinking about something like:

/*
 * @oas [get] /pet/{petId}
 * description: "Returns all pets from the system that the user has access to"
 * parameters:
 *   - (path) petId=hi* {String} The pet ID
 *   - (query) limit {Integer:int32} The number of resources to return
 *   - (query) sort_by {String} The field to sort by [version<=1]
 *   - (query) size {String} Size of the pet to filter by
*/

Please note [version <= 1]

WDYT ? Is this in your pipeline ? Do you have any hint on how to implement it ?

[ggobbe]

Atm you can use scope: v1 or scope: v1, v2 on your endpoint documentation then you can narrow your OpenApi file generation to a given scope:

oas generate --scope v1

[erunion]

With the release of v20 this library no longer has a CLI offering for creating OpenAPI definitions. If you'd like to still support the idea behind this ticket I recommend moving it over to swagger-inline[^1].

[^1]: The internal library that the oas CLI has always used for OpenAPI generation.