Adding readonly attribute using Azure Functions OpenAPI extension

Question

We are migrating an Azure Function app from .NET Framework 4.8 to .NET 6.0.

The old version uses several custom attributes on the model properties to control what is shown in the generated swagger OpenAPI 2.0 documentation - including "Required" and "Readonly".

For example, when generating the swagger docs when a model has both read/create operations, it uses the readonly attribute to "hide" the properties that are not accepted on create. The same property is not hidden on the read call, since the server has populated it at that point.

The new function app is using the provided Microsoft.Azure.WebJobs.Extensions.OpenApi extension to generate the OpenAPI 3.0 docs and we want to find a way to add this same "readonly" functionality.

Does anyone have an idea on how this could be done?

An example model from the old application:

public class ThingModel
{
    [Display(Name = "Thing Id", Description = "Thing Model Id")]
    [ReadOnly(true)]
    public Guid? Id { get; set; }

    [Display(Name = "Thing Name", Description = "Name of Thing")]
    [Attributes.Required(HttpMethodType.Post)]
    public string Name { get; set; }

    [Display(Name = "Thing Description", Description = "Description of Thing")]        
    public string Description { get; set; }
}

The documentation for the nuget package has many attributes defined, but "readonly" is not one of them: https://github.com/Azure/azure-functions-openapi-extension/blob/main/docs/openapi-core.md

Rajesh Mopati · Accepted Answer · 2023-03-06 05:07:58Z

Thanks to mnemcik-visma

There is no particular field as readOnly. While using the API first approach, need to use the same data model as an input and output of the API call, obviously to limit the duplication of definitions. Using readOnly attribute to indicate the fields that are not meant to be set by the client application as the input fields.

The Microsoft.Azure.WebJobs.Extensions.OpenApi extension generates the OpenAPI 3.0 documentation for Azure Functions app. To add the "readonly" functionality, you can use the "readOnly" property in the JSON schema definition of the property.

To define the "readOnly" property in the JSON schema definition of the "Id" property in your ThingModel class:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "Id": {
      "type": "string",
      "format": "uuid",
      "readOnly": true
    },
    "Name": {
      "type": "string"
    },
    "Description": {
      "type": "string"
    }
  }
}

enter image description here

Here is another example of how you can define the "readOnly" property in the schema for the "ThingModel" class:

openapi: 3.0.0
info:
  title: Thing Model API
  version: 1.0.0
paths:
  /thing:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ThingModel'
      responses:
        '200':
          description: Success
components:
  schemas:
    ThingModel:
      type: object
      properties:
        Id:
          type: string
          format: uuid
          readOnly: true
        Name:
          type: string
          required: true
        Description:
          type: string

In this example, the "Id" property is defined as read-only by setting the "readOnly" property to "true".

For more information on properties.

Collectives™ on Stack Overflow

Adding readonly attribute using Azure Functions OpenAPI extension

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related