dotnet / dotnet/docfx

[Feature Request] Generate OperationId Field When Missing

Open
#10,845 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C#
Stars
4.4k
Forks
890
Avg merge
2h 11m
Merged PRs (30d)
10

Description

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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.