Swagger Editor, how to add additional “hidden” information?
Multi tool use
Swagger Editor, how to add additional “hidden” information?
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?
1 Answer
1
First of all, the OpenAPI Specification provides the operationId keyword that some tools map to method names.
operationId
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.
x-
x-swagger-router-controller
paths:
/foo:
x-swagger-router-controller: users
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
– user2883596
Jul 2 at 15:28
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. Swagger Codegen appears to be using operationId in some code generators.– Helen
Jul 2 at 15:46
operationId
operationId
operationId
By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.
Related: Can I add versions to YAML Swagger objects?
– Helen
Jul 2 at 11:06