renamed to follow swagger docs
comments & clean-up