1

I use swagger editor to declare some of my routing endpoints to the public, however, I would like to add my router function name (the controlling function) to my endpoint paths as additional information, but just as an info for me (private). E.g. to recognize which function middleware I use for a specific route. Is that somehow possible, if yes, how?

MMMM
  • 3,320
  • 8
  • 43
  • 80
  • Related: [Can I add versions to YAML Swagger objects?](https://stackoverflow.com/q/46077562/113116) – Helen Jul 02 '18 at 11:06

1 Answers1

1

First of all, the OpenAPI Specification provides the operationId keyword that some tools map to method names.

paths:
  /users:
    get:
      operationId: getUsers
      ...
    post:
      operationId: addUser
      ...

You can also add arbitrary custom keys prefixed with x- (so-called extension properties). A common extension property is x-swagger-router-controller to specify the controller class.

paths:
  /foo:
    x-swagger-router-controller: users
Helen
  • 87,344
  • 17
  • 243
  • 314
  • ok thanks, operationId worked, but has it also any useful function? I mean it helps me remember what function it was that I defined for that route, thats what I wanted. But besides that, has it more usefulness, e.g. in automatic swagger doc creation or so? I did everything manually in the editor for now... as the function to create the API from my repository does not work automatically yet :( The x-.... tags are viewable in the editor... so its not so my usecase – MMMM Jul 02 '18 at 15:28
  • 1
    There are lots of tools that support OpenAPI/Swagger, so there's no definite answer - some tools may have a specific use for `operationId` while others may not use it at all. Just a couple of examples: Swagger UI uses `operationId` for [permalinks](https://stackoverflow.com/q/45147928/113116). [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) appears to be using `operationId` in [some code generators](https://github.com/swagger-api/swagger-codegen/search?q=operationid). – Helen Jul 02 '18 at 15:46