Auto-generate nicer operationIds for deep linking / permalinks in Swagger-UI?

[michalrus]

So if there’s no explicit operationId, Swagger-UI will generate fragment names for their deepLinking.

But those fragment names are rather ugly.

Also they have a history of breaking deep linking, see:

• Permalinks don’t work: with tags, and docExpansion: 'none', for operations that don’t have an explicit operationId. swagger-api/swagger-ui#4929
• Deep linking does not work without operationId swagger-api/swagger-ui#4895

Also not all characters are accepted, instead of being correct w.r.t. Swagger validator.

This snippet will add explicit operationIds that work and look nice in the permalink URL, e.g.:

• PUT.v1.permission.role.RoleId.user.me.UserId
• POST.v1.user.instant-check.email

-- |A fix for <https://github.com/swagger-api/swagger-ui/issues/4929>.
addExplicitOperationIds :: Swagger -> Swagger
addExplicitOperationIds =
  over
    paths
    (InsOrd.mapWithKey
       (\path ->
          let f method method' = over method (map (setId method' path))
           in f get "GET" . f put "PUT" . f post "POST" . f Data.Swagger.delete "DELETE" .
              f options "OPTIONS" .
              f head_ "HEAD" .
              f patch "PATCH"))
  where
    setId :: Text -> FilePath -> Operation -> Operation
    setId method path = over operationId (<|> (Just . swaggerUiAcceptedId $ method ++ pack path))

swaggerUiAcceptedId :: Text -> Text
swaggerUiAcceptedId =
  intercalate "." . filter (not . null) . T.split (\c -> not (C.isAlphaNum c || c == '-'))

---

Note: this probably can be closed immediately, I just wanted to leave this simple copy-paste somewhere indexable for people that will face this problem.