Skip to main content

Published API documentation is not formatted correctly

Symptom​

The published API documentation is not formatted correctly (for example, a duplicate operationId across two routes produces overlapping entries on the published landing page instead of two distinct ones) and you see any of the following errors:

Example error 1​

(restapi/lexicon-V2.json)Uid(Lexicon Service V2/Add) has already been defined in restapi/lexicon-V2.json

Example error 2​

(restapi/sentry.json)Uid(Sentry API/2.0/GetUserAsync) has already been defined in restapi/sentry.json

Solution​

All operationIds for each route in the JSON input file must be unique. Developers should do this when they add/update the JSON for each API.

Option 1: Must only be done once​

  • Modify the Startup.cs class for the API to generate custom operationIds for each route (this has proven successful).
  • Put an attribute above each API route that denotes what the operationId should be set to. It's manual, but you only have to do it once and add it for each new route.

Option 2: Must be done every time a new Swagger file is ready​

  • Manually edit the JSON file to make the operationIds unique (not recommended).