Filter OpenAPI REST methods and fields based on role #2998

Copilot · 2025-12-01T18:33:58Z

Why make this change?

Closes #2787 - OpenAPI REST methods should show only available methods

The current OpenAPI behavior shows all REST methods even when they are not available. For example, read-only entities show all REST methods (GET, POST, PUT, PATCH, DELETE) in the OpenAPI document, which misrepresents the available options.

Related issues:

[Bug]: OpenAPI and $filter for dates #2783 - OpenAPI and $filter for dates (DB → OpenAPI type mapping - separate PR)
[Bug]: Incorrect OpenAPI Specifiaction causes error in Swagger #2486 - Incorrect OpenAPI Specification causes error in Swagger (separate PR)
[Enh]: Reflect the HTTP headers in the OpenApi document #2896 - Add If-Match and Cache-Control Headers (separate PR)

What is this change?

Permission-based filtering (OpenApiDocumentor.cs):

GetConfiguredRestOperations - Filters operations based on permissions superset across all roles
FilterFieldsByPermissions - Filters fields based on include/exclude settings across all roles
HasAnyAvailableOperations - Checks if entity has any permissions with actions defined
Entities with no available operations are completely omitted (no paths, tags, or schemas)

Role-specific OpenAPI endpoint (RestController.cs):

/openapi - Returns superset of all roles (existing behavior)
/openapi/{role} - Returns OpenAPI document filtered for a specific role
Case-insensitive role matching with URL-decoded parameter
Returns 404 if role not found or empty/whitespace

Request Body Strict Mode:

Request body schemas (_NoAutoPK, _NoPK, _sp_request) set AdditionalPropertiesAllowed based on RuntimeConfig.IsRequestBodyStrict
When request-body-strict: true (default): additionalProperties: false
When request-body-strict: false: additionalProperties: true
Response body schemas always allow additional properties

Wildcard (*) Behavior:

Tables/Views: * expands to all CRUD operations (Create→POST, Read→GET, Update→PUT/PATCH, Delete→DELETE)
Stored Procedures: * maps to Execute only; HTTP methods determined by entity.Rest.Methods

Permission → REST mapping:

Permission	REST Methods
Read	GET
Create	POST
Update	PUT, PATCH
Delete	DELETE

Code Review Fixes:

Added empty/whitespace validation for role parameter
Replaced foreach loop with LINQ .Any() for role existence check
Simplified AdditionalPropertiesAllowed ternary expression
Simplified field filtering logic with ternary operator
Improved comment clarity for catch block behavior

How was this tested?

Integration Tests
Unit Tests

Tests split into focused files:

OperationFilteringTests.cs - Operation filtering tests (read-only, wildcard, no permissions, mixed roles)
FieldFilteringTests.cs - Field filtering tests (excluded fields, mixed role field permissions)
RoleIsolationTests.cs - Role isolation tests (anonymous vs superset, competing roles don't leak)
RequestBodyStrictTests.cs - Request-body-strict tests

Sample Request(s)

Superset OpenAPI (all roles combined):

GET /api/openapi

Role-specific OpenAPI:

GET /api/openapi/anonymous
GET /api/openapi/authenticated
GET /api/openapi/customrole

Returns 404 if role doesn't exist in any entity's permissions.

Config with read-only entity:

{
  "entities": {
    "Book": {
      "source": "dbo.books",
      "permissions": [
        { "role": "anonymous", "actions": ["read"] }
      ]
    }
  }
}

OpenAPI response shows only GET operations for /Book and /Book/id/{id} paths.

Config with excluded field:

{
  "entities": {
    "Book": {
      "source": "dbo.books",
      "permissions": [
        { 
          "role": "anonymous", 
          "actions": [{ "action": "*", "fields": { "exclude": ["secret_column"] } }]
        }
      ]
    }
  }
}

OpenAPI schema for Book entity will not include secret_column in its properties.

Config with competing roles:

{
  "entities": {
    "Book": {
      "source": "dbo.books",
      "permissions": [
        { "role": "reader", "actions": ["read"] },
        { "role": "writer", "actions": ["create"] }
      ]
    }
  }
}

/openapi shows GET (from reader) and POST (from writer) operations
/openapi/reader shows only GET operations
/openapi/writer shows only POST operations
/openapi/admin returns 404 (role not found)

Original prompt

This section details on the original issue you should resolve

<issue_title>[Enh]: OpenAPI REST methods should show only available methods</issue_title>
<issue_description>## What?

Show only the available REST methods in the OpenAPI document we produce.

Why?

The current OpenAPI behavior shows all REST methods even when they are not available.

For example, read-only entities show all the REST methods in the OpenAPI document.

How?

Available REST methods are limited in permissions for each role. In order to correctly show the available REST methods, we need to interrogate the current role and produce the role-specific OpenAPI that filters REST methods based on that role's permissions for each entity.

Notes

This does not require a change to the configuration. </issue_description>

<agent_instructions>Your goal is to satisfy this requirement with as little change or introduction of code as possible. Follow best practices and do not skip tests, but at the same time, do NOT introduce unnecessary code. Think and rethink if there is a simpler solution and ALWAYS choose the simplest and easiest and most terse that satisfies the requirement. You are a Principal Software Engineer at Microsoft on the Data API builder ENG team. Your code is intended to be an example to follow. Go. </agent_instructions>

Comments on the Issue (you are @copilot in this section)
@JerryNixon The current root OpenAPI shows the superset of the available permissions across all roles. If there are permissions for anonymous, authenticated, or custom roles, the root OpenAPI should show what is possible across all of them combined, not specific to any one role. However, if a permission like delete is not available to any role or a method is not available because there is no permission set (remembering that * represents create, read, update, and delete for tables and views while * represents execute for stored procedures) then those unavailable methods should be omitted from the root OpenAPI because it misrepresents the available options.

Fixes [Enh]: OpenAPI REST methods should show only available methods #2946

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Co-authored-by: JerryNixon <[email protected]>

JerryNixon · 2025-12-01T19:01:26Z

@copilot An entity with no possible methods should be completely omitted from the OpenAPI specification.

…ased on permissions Co-authored-by: JerryNixon <[email protected]>

Copilot · 2025-12-01T19:24:59Z

@copilot An entity with no possible methods should be completely omitted from the OpenAPI specification.

Implemented in commit 92da2fe. Entities with no available operations are now completely omitted from the OpenAPI specification - no paths, no tags, and no component schemas are generated for them. The HasAnyAvailableOperations helper and checks in BuildPaths, CreateDocument, and CreateComponentSchemas ensure this behavior.

JerryNixon · 2025-12-01T19:33:21Z

@copilot Now take time to account for fields in the same way. Please note that fields are in the permissions / role / actions / fields property and can be designated in the configuration file with the * wildcard to indicate all and that there is both include and exclude which work together to create the available fields and that all of this is option in the configuration if the developer wants to simply expose all fields. That said, we cannot expose fields which are expressly excluded or not included.

Co-authored-by: JerryNixon <[email protected]>

Copilot · 2025-12-01T19:39:01Z

@copilot Now take time to account for fields in the same way. Please note that fields are in the permissions / role / actions / fields property and can be designated in the configuration file with the...

Implemented in commit 48c76ae. Added FilterFieldsByPermissions method that:

Returns superset of available fields across all role/action permissions
Handles Include (null or * means all fields, otherwise explicit list)
Handles Exclude (removes specified fields, * excludes all)
If Fields is null on an action, all fields are available

The filtering is applied in CreateComponentSchemas right after getting exposed column names. Added tests for excluded fields and mixed role field permissions.

JerryNixon · 2025-12-01T19:44:47Z

@copilot Check that "none" and "anonymous" are not the same. As none should represent all roles together, anonymous is an explicit role like authenticated or some other custom role the user adds.

The next thing is to ensure that calling a single role results in what we want. I would like to see a test for this to ensure it works when, say, two competing roles are defined and the resulting openapi is correctly reprenseting the individual roles and not leaking information into the others.

Co-authored-by: JerryNixon <[email protected]>

Copilot · 2025-12-01T19:51:25Z

@copilot Check that "none" and "anonymous" are not the same. As none should represent all roles together, anonymous is an explicit role like authenticated or some other custom role the user adds.

Th...

Implemented in commit 178910f:

Role distinction: The filtering methods now have an optional role parameter. When null (no role specified), it returns the superset of all roles. When a specific role like "anonymous" is provided, it filters to only that role's permissions using case-insensitive comparison.
Tests for competing roles:
- AnonymousRole_IsDistinctFromSuperset - Verifies anonymous is a specific role, not the superset
- CompetingRoles_DoNotLeakOperations - Reader role has only READ, writer role has only CREATE; superset has GET+POST but not PUT/PATCH/DELETE
- CompetingRoles_DoNotLeakFields - Reader sees 'id', writer sees 'title'; superset correctly combines both without leaking

JerryNixon · 2025-12-01T19:55:48Z

@copilot Keep refactoring and simplifying. Remember we want to have good code coverage specifically for the lines you introduced in this PR. We also want to ensure existing tests that also might touch the code are updated or removed if required. Your goal is simplicity while still fulfilling the requirements. Every unit test should in this PR should test the code we introduced.

In addition, look at the routing to the OpenAPI endpoint. It is basically /OpenAPI which should have no role and shows the superset. But let's amend this to support /OpenAPI/{role} where this is how the user would indicate the unique role OpenAPI document they would like to see. This would take advantage of the code we just wrote. Make this case-insensitive and if the role is not found, it is a simple 404. There is no auth for the OpenAPI. The goal is not security but clarity so roles have the option to understand what they are allowed to do.

Co-authored-by: JerryNixon <[email protected]>

Copilot · 2025-12-01T20:05:28Z

@copilot Keep refactoring and simplifying. Remember we want to have good code coverage specifically for the lines you introduced in this PR. We also want to ensure existing tests that also might touch...

Implemented in commit ae8166c:

Refactored and simplified: Methods now use optional role parameter consistently
Added /openapi/{role} routing:
- /openapi returns superset of all roles
- /openapi/{role} returns role-specific OpenAPI document
- Case-insensitive role matching
- URL-decoded role parameter for safety
- Returns 404 if role not found in any entity's permissions
Tests for competing roles: Added tests to verify operations and fields don't leak between roles

Copilot

Pull request overview

This PR implements permission-based filtering for OpenAPI REST endpoint documentation. The changes allow the OpenAPI document to show only REST methods and fields that are available based on entity permissions, with support for both a superset view (all roles combined) and role-specific filtered views.

Key changes:

Permission-based operation filtering that maps CRUD permissions to HTTP methods (Read→GET, Create→POST, Update→PUT/PATCH, Delete→DELETE)
Role-specific OpenAPI endpoint (/openapi/{role}) in addition to the existing superset endpoint (/openapi)
Field-level filtering based on include/exclude configurations across role permissions
Request body strict mode support via additionalProperties schema setting

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
src/Service/Controllers/RestController.cs	Adds role-specific OpenAPI endpoint handling at `/openapi/{role}` with URL decoding and case-insensitive role matching
src/Core/Services/OpenAPI/OpenApiDocumentor.cs	Implements core filtering logic for operations and fields based on permissions, with role-specific document generation
src/Core/Services/OpenAPI/IOpenApiDocumentor.cs	Adds interface method `TryGetDocumentForRole` for role-specific OpenAPI document retrieval
src/Service.Tests/OpenApiDocumentor/OperationFilteringTests.cs	Tests for operation filtering including read-only, wildcard, and mixed-role scenarios
src/Service.Tests/OpenApiDocumentor/FieldFilteringTests.cs	Tests for field-level filtering with exclude/include configurations
src/Service.Tests/OpenApiDocumentor/RoleIsolationTests.cs	Tests ensuring role permissions don't leak between roles
src/Service.Tests/OpenApiDocumentor/RequestBodyStrictTests.cs	Tests for request-body-strict mode affecting additionalProperties setting
src/Service.Tests/OpenApiDocumentor/OpenApiTestBootstrap.cs	Adds support for configuring request-body-strict setting in test bootstrap

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-02T18:23:24Z