Skip to content

[Feature Request] Generate OperationId Field When Missing #10845

@TheBrambleShark

Description

@TheBrambleShark

I'm a little torn on whether this should be a bug report or a new feature. The real issue here is a lack of documentation on the OpenAPI feature and not mentioning the fact that the optional OperationId field (per OpenAPI v2 specifications) is actually required. The sample does include the fields on each of the endpoints, but the inclusion of an optional field in an example isn't particularly noteworthy.

Is your feature request related to a problem? Please describe.
The OpenAPI V2 Specification does not require the OperationId field to be specified, but failing to do so will cause DocFx to not generate the API documentation. It appears that the DocFx engine uses the OperationId field to produce the endpoint names.

To Reproduce
Steps to reproduce the behavior:

  1. Specify an OpenId V2 file without OperationId fields for consumption in docfx.json.
  2. Generate the documentation with docfx docfx.json --serve
  3. Note the error generated in the output:

C:\Projects\Documentation\documentation.contoso.com\rest\users.v8.swagger.json: error InvalidInputFile: Unable to load file 'rest/users.v8.swagger.json' via processor 'RestApiDocumentProcessor': operationId should exist in operation 'get' of path '/api/v8/pending/User/{departmentAbbreviation}/{employeeIdNumber}' for swagger file 'rest/users.v8.swagger.json'

This doesn't prevent the site from generating, but the API documentation page(s) for the files missing OperationId fields are not generated, leading to incomplete output.

Describe the solution you'd like
DocFx should have the capability of generating missing OperationIds in the event they are missing. This behavior should not override any manually specified OperationId fields.

For instance, GET /api/v8/User/{employeeIdNumber} should result in getV8UserByEmployeeIdNumber.

Describe alternatives you've considered
I have an open PR (Ellerbach/docfx-companion-tools#117) to add the generation feature to the DocFxOpenApi tool, but I feel this should be a native feature.

Additional context
Add any other context or screenshots about the feature request here.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions