Support "readOnly" and "writeOnly" OpenAPI properties

[Rycochet]

See https://swagger.io/docs/specification/data-models/data-types/#readonly-writeonly

These modifiers are on specific properties and allow for a single definition to be used in both read & write endpoints, but provide a different shape to each -

// ... "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
  }
}

Currently this just generates a single interface similar to -

export interface components {
  schemas: {
    Data: {
      id: number;
      username: string;
      password: string;
    };
  };
}

Unfortunately that makes it unusable for any endpoint as GET doesn't show the password and POST etc doesn't want an id. One way to change this is to use multiple interfaces (alternatively using a suffix for the schema might be suitable - but there is a possibility of a name clash that way) - possibly something like -

export interface components {
  read_schemas: {
    Data: {
      id: number;
      username: string;
    };
  };
  write_schemas: {
    Data: {
      username: string;
      password: string;
    };
  };
  schemas: {
    Data: components["read_schemas"]["Data"] | components["read_schemas"]["Data"];
  }
}

Alternatively it could go the other way around, although I feel this makes the typing slightly less useful (adding type guards to code is pretty simple, but they like the union types more) -

export interface components {
  read_schemas: {
    Data: components["schemas"]["Data"] & {
      id: number;
    };
  };
  write_schemas: {
    Data: components["schemas"]["Data"] & {
      password: string;
    };
  };
  schemas: {
    Data: {
      username: string;
    };
  }
}

If there's no readOnly or writeOnly properties then nothing would need to change for any schemas that don't use them.

[drwpow]

Interesting! I had been wondering if readOnly and writeOnly needed representation in TypeScript somehow, but I had personally never used them in a schema. Your example makes sense.

In the past, I’ve been bitten by trying to remap or rename generated types. Because no matter how clever you think you are, there’s always some wild schema someone uses that breaks your assumptions, and you have to release a breaking version (that’s v1 of this library in a nutshell)! So I’m hesitant to have dynamically-generated components that don’t exist in your schema, but I do agree with coming up with some solution.

We could possibly do something clever with Extract<> or Pick<> inside responses and requests? In other words, we leave components["schemas"]["Data"] alone, but modify the properties returned for responses[…] and requests[…] (basically wherever it’s referenced)?

[Rycochet]

That's pretty much what I'm doing now (but with Omit<> due to length - so I only need to add the ones that come from the "opposite" side):

// as Omit
export type IReadData = Omit<"password", components["schemas"]["Data"]>;
export type IWriteData = Omit<"id", components["schemas"]["Data"]>;

// as Pick
export type IReadData = Pick<"id" | "username", components["schemas"]["Data"]>;
export type IWriteData = Pick<"username" | "password", components["schemas"]["Data"]>;

Of the two the Pick is definitely clearer what is inside there, but if the properties are pretty long it could make for a lot of duplication - not exactly a problem for generated code, and far easier to just look at it to see what's included in there - Prettier can handle the line length!)

The potential downside I can see is that components["schemas"]["Data"] is not a union, and is instead assumed to be totally that content, which means code using it could be wrong by accessing both id and password in the same code (type guard + union ftw lol).

Having those read and write within the requests and responses would make it a lot safer though, and for that reason alone makes a lot of sense.

At the very least, adding comments to the end of the schema lets the person reading see that there's something going on? (Could do before, but that can get mixed up with the description if it exists, looking at the code adding a comment to the end isn't done anywhere?)

export interface components {
  schemas: {
    Data: {
      id: number; // response only
      username: string;
      password: string; // request only
    };
  }
}

[Rycochet]

Ok, put a bit of time into this - and got code in there that works, however using Pick<> style actually doesn't work - nested properties breaks it. The root property will be correct, but anything further down doesn't know that it should be in a readonly / writeonly state - will have a try with the multiple-schema style instead but wanted to report that back before anyone else spends time on it!

[olivierbeaulieu]

Hi! I've keeping an eye on this issue for a while and finally decided to take a stab at it. I think I've found a pretty simple solution that doesn't rely on Pick or Omit, and it seems to work pretty well. I haven't written tests yet, but I wanted to share the approach here and get some feedback: https://github.com/drwpow/openapi-typescript/compare/main...olivierbeaulieu:pr/read-write-only?expand=1

In short, we simply add a generic param on the top-level interfaces (components), and set the mode to 'read' or 'write' depending on whether we're looking at a request or a response context. We pass down this generic value every time we consume a $ref, allowing this to work with nested properties.

A few key points:

1. Importing the schema directly keeps the same behaviour as before, readOnly and writeOnly are ignored
2. It's easy to get a reference to either version of the schema (components<'read'>['schemas']['MySchema'])

If the approach makes sense, I can get the PR up shortly.

[bryanhoulton]

Any progress on this? Running into similar issues.

[tnagorra]

I tried the approach described by @olivierbeaulieu with minor changes.
The approach works nicely.

[ashe0047]

I tried the approach described by @olivierbeaulieu with minor changes. The approach works nicely.

How did you implement the approach mentioned by @olivierbeaulieu ? Do you mind sharing what changes to make after generating the types using this library?

[H01001000]

Sorry for asking but any update?

[elmarsto]

Is there anything I can do to expedite this? Some frameworks, like Django, use this feature of OpenAPI extensively. At the moment I'm stuffing extra fields into my requests just to make openapi-fetch happy, which is a pity because the whole point of using it was to get a 1:1 correspondence between frontend and backend :/