readOnly and writeOnly properties

[Rycochet]

This is a basic implementation for #604

Globally this adds a comment to the end of fields that only exist in readOnly or writeOnly form, but it also adds an optional -s / --splitSchema flag that will instead create a slightly different structure.

Data -

// ... "Data": { ...
"properties": {
  "id": { // Returned by GET, not used in POST/PUT/PATCH
    "type": "integer",
    "readOnly": true
  },
  "username": {
    "type": "string"
  },
  "password": { // Used in POST/PUT/PATCH, not returned by GET
    "type": "string",
    "writeOnly": true
  }
}

Without the flag -

export interface components {
  schemas: {
    Data: {
      id: number; // GET requests only
      username: string;
      password: string; // POST/PUT/PATCH responses only
    };
  };
}

With -s / --splitSchema

export interface components {
  "x-requestSchemas": {
    Data: {
      id: number; // GET requests only
      username: string;
    };
  };
  "x-responseSchemas": {
    Data: {
      username: string;
      password: string; // POST/PUT/PATCH responses only
    };
  };
  "schemas": {
    Data: components["x-requestSchemas"]["Data"] | components["x-responseSchemas"]["Data"];
  }
}

Not shown, but with the flag any request or response fields with a $ref will point at the correct interface (and anything outside of there will point at the base schemas) - Typescript will understand what to do if you point at those rather than the base schemas data (which can be used with typeguards for simpler source).

There are minimal tests just to check it is working in general (something testing the cli flag would be far better).

There is also no checking of if it is required - that is fully up to the user.

Ideally a better solution would check if it is needed anywhere in the data tree, and then only use the split schema in that case, and keep it in the main schemas structure otherwise, however given the simple structure of the code this would add a lot of overhead, and would be best with a rewrite of the logic being used (not something I really want to think about given the amount of time it could take).

Technically readOnly is supported in both v2 & v3, however writeOnly is only supported in v3 (similar to how additionalProperties gets a slightly different meaning between the versions) - yet another reasons to leave this behind a flag rather than as a default.

[codecov]

Codecov Report

Merging #621 (648fb44) into main (c09ace1) will decrease coverage by 5.15%.
The diff coverage is 72.97%.

❗ Current head 648fb44 differs from pull request most recent head 7ab07fb. Consider uploading reports for the commit 7ab07fb to get more accurate results

@@            Coverage Diff             @@
##             main     #621      +/-   ##
==========================================
- Coverage   93.52%   88.37%   -5.16%     
==========================================
  Files          11       10       -1     
  Lines         510      413      -97     
  Branches      183      153      -30     
==========================================
- Hits          477      365     -112     
- Misses         32       48      +16     
+ Partials        1        0       -1     

Impacted Files	Coverage Δ
src/transform/index.ts	81.81% <45.45%> (-6.12%)	⬇️
src/transform/schema.ts	93.54% <76.47%> (-4.05%)	⬇️
src/index.ts	80.00% <100.00%> (-9.10%)	⬇️
src/transform/operation.ts	100.00% <100.00%> (ø)
src/utils.ts	92.98% <100.00%> (-1.76%)	⬇️
src/transform/headers.ts	23.07% <0.00%> (-76.93%)	⬇️
src/transform/responses.ts	84.21% <0.00%> (-5.27%)	⬇️
src/transform/paths.ts	92.00% <0.00%> (-0.31%)	⬇️
... and 3 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 6d9854c...7ab07fb. Read the comment docs.

[drwpow]

This is really clever! I like your implementation. And the usage of a flag is great. I don’t see any conflict that could happen, since technically components["responseSchemas"] is an unused space, I think that will generate nicely.

Bikeshedding a little, I was seeing if the OpenAPI spec allows unknown fields in the components object. I think it does, as it doesn’t specifically disallow it, but it does give this hint:

This object MAY be extended with Specification Extensions (x-*)

What do you think about x-requestSchemas and x-responseSchemas instead for --splitSchema? Though I think your implementation may work, the x-* prefix would seem to make it a little more OpenAPI compliant. Open to your thoughts there.

[Rycochet]

Adding the x- prefix makes a lot of sense - will fix the conflicts and update for that :-)

[mrdannael]

Hi! What is the status of this PR? 😃 This is something that i'm looking for currently 🥇

[Rycochet]

Hi! What is the status of this PR? 😃 This is something that i'm looking for currently 🥇

It was all ready to merge and then nothing happened - I've moved on to other things but anyone is welcome to take over the work on it!

[YuJianrong]

May I ask is there any update on this PR? It's created almost one year ago...

[Fi1osof]

Waiting too(((

[prevostjules]

Hi,

Would it be possible to have updates on that great feature ? Is a merge planned soon ? :)

Thanks all for your terrific work