{"id":16852661,"url":"https://github.com/avdv/api-doc","last_synced_at":"2025-03-18T10:16:58.940Z","repository":{"id":36017440,"uuid":"40312219","full_name":"avdv/api-doc","owner":"avdv","description":"A non-cluttering swagger doc for scala playframework","archived":false,"fork":false,"pushed_at":"2015-08-07T14:54:23.000Z","size":1310,"stargazers_count":0,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-24T16:35:25.880Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/avdv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-06T15:24:50.000Z","updated_at":"2021-01-26T11:59:04.000Z","dependencies_parsed_at":"2022-08-26T22:52:04.241Z","dependency_job_id":null,"html_url":"https://github.com/avdv/api-doc","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avdv%2Fapi-doc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avdv%2Fapi-doc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avdv%2Fapi-doc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avdv%2Fapi-doc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/avdv","download_url":"https://codeload.github.com/avdv/api-doc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244198395,"owners_count":20414443,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-13T13:48:10.785Z","updated_at":"2025-03-18T10:16:58.914Z","avatar_url":"https://github.com/avdv.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\n\nAPI-doc\n=========\n\nNon-cluttering swagger doc for scala playframework.\n\nThis API-doc does the following validation checks:\n\n  * All endpoints must be documented\n  * The endpoints in the api docs must match the endpoints in conf/routes\n  * All used datatypes must be defined\n  * Datatypes must have corresponding scala classes.\n  * The fields in datatypes must be the same as the fields in the corresponding scala classes.\n  * Datatypes can only be defined once\n\n\n\nPlay 2.3 vs. Play 2.4\n=====================\n\nThe master branch uses Play 2.4\nPlay 2.3 is supported in the play_2.3 branch.\n\n\n\nQUICK START\n===========\n\n1. execute \"activator run\" in the terminal.\n\n2. Go to this address in your browser:\n\n   http://localhost:9000/swagger-ui/dist/index.html?url=http://localhost:9000/api/v1/api-docs\n\n\n\nHOW TO USE IN YOUR OWN PROJECT (QUICK AND DIRTY)\n================================================\n\n\n1. Add api-doc dependency to build.sbt:\n\n  ```\n  resolvers += \"jitpack\" at \"https://jitpack.io\"\n  libraryDependencies += \"com.github.sun-opsys\" % \"api-doc\" % \"0.9.9\"\n  ```\n\n\n2. If webjars is not a dependency in your project, add these lines to build.sbt:\n   ```\n   libraryDependencies ++= Seq(\n      \"org.webjars\" %% \"webjars-play\" % \"2.4.0-1\"\n   )\n   ```\n\n\n3. Add the following line to conf/routes:\n   ```\n   GET   /webjars/*file    controllers.WebJarAssets.at(file)\n   GET   /api/v1/api-docs  controllers.ApiDocController.get()\n   ```\n   \n4. Create the controller:\n\n   ```scala\n  package controllers\n  \n  import play.api._\n  import play.api.mvc._\n  \n  import no.samordnaopptak.apidoc.ApiDoc\n  import no.samordnaopptak.apidoc.{AnnotationHelper, RoutesHelper, RouteEntry, SwaggerUtil}\n\n  class ApiDocController extends Controller {\n    @ApiDoc(doc=\"\"\"\n      GET /api/v1/api-docs\n  \n      DESCRIPTION\n        Get main swagger json documentation\n    \"\"\")\n    def get() = Action {\n      val apidocs = AnnotationHelper.getApiDocsFromAnnotations()\n      Ok(SwaggerUtil.getMain(\"/\", apidocs).asJsValue)\n    }\n  }\n  ```\n\n5. Now the api-docs should be available at the following address:\n   ```\n   /webjars/api_doc/1.0/swagger-ui/dist/index.html?url=/api/v1/api-docs\n   ```\n\n\nExamples\n==========\n\nBasic usage:\n\n\n    @no.samordnaopptak.apidoc.ApiDoc(doc=\"\"\"\n      GET /api/v1/users/{id}/{type}\n\n      DESCRIPTION\n        Get user\n\n      PARAMETERS \n        id: String \u003c- The user id\n        type: Enum(Woman, Man, Dog) String \u003c- The user can either be a woman, a man, or a dog.\n\n      ERRORS\n        400 User not found\n        400 Syntax Error\n    \"\"\")\n    def getUser(id: String) = ...\n\n\n\nDefine parameter types:\n\n    @no.samordnaopptak.apidoc.ApiDoc(doc=\"\"\"\n      GET /api/v1/users/{phone}/{age}\n\n      DESCRIPTION\n        Get user\n\n      PARAMETERS \n        id: String(path)                 \u003c- 'path' parameter type (default, unless the parameter name is 'body')\n        body: String                     \u003c- 'body' parameter type.\n        phone: String(query)             \u003c- 'query' parameter type\n        mobile: String(query, optional)  \u003c- Optional 'query' parameter type\n        email: String(form)              \u003c- 'form' parameter type\n        age: Enum(10,20,30,40) Int       \u003c- Enum Int parameter. (also a 'path' parameter type)\n    \"\"\")\n    def getUser(id: String) = ...\n\n\n\nDefining types:\n\n    case class User(id: String, firstName: String)\n\n    @no.samordnaopptak.apidoc.ApiDoc(doc=\"\"\"\n      GET /api/v1/users/{id}\n\n      DESCRIPTION\n        Get user\n\n      PARAMETERS \n        id: String \u003c- Parameter comment\n\n      ERRORS\n        400 User not found\n        400 Syntax Error\n\n      RESULT\n        User\n\n      User:\n        id: String\n        firstName: String          \u003c- The first name of the user.\n        age: Enum(10,20,30,40) Int \u003c- Age can be either 10, 20, 30 or 40\n        nickNames: Array String    \u003c- All nickNames in an array of strings\n    \"\"\")\n    def getUser(id: String) = ...\n\n\n\n\n\nDefining types, based on an almost matching existing class:\n\n    case class User(id: String, firstName: String)\n\n    @no.samordnaopptak.apidoc.ApiDoc(doc=\"\"\"\n      GET /api/v1/users/{id}\n\n      DESCRIPTION\n        Get user\n\n      PARAMETERS \n        id: String \u003c- Parameter comment\n\n      ERRORS\n        400 User not found\n        400 Syntax Error\n\n      RESULT\n        User\n\n      User(-firstName, +lastName):\n        id: String\n        lastName: String\n    \"\"\")\n    def getUser(id: String) = ...\n\n\n\n\nDefining types, based on an almost matching existing class, using @JsonIgnore:\n\n    import com.fasterxml.jackson.annotation._\n    case class User(id: String, @JsonIgnore firstName: String)\n\n    @no.samordnaopptak.apidoc.ApiDoc(doc=\"\"\"\n      GET /api/v1/users/{id}\n\n      DESCRIPTION\n        Get user\n\n      PARAMETERS \n        id: String \u003c- Parameter comment\n\n      ERRORS\n        400 User not found\n        400 Syntax Error\n\n      RESULT\n        User\n\n      User(+lastName):\n        id: String\n        lastName: String\n    \"\"\")\n    def getUser(id: String) = ...\n\n\n\n\nDefining types, based on a class defined elsewhere:\n\n    @no.samordnaopptak.apidoc.ApiDoc(doc=\"\"\"\n      GET /api/v1/users/{id}\n\n      DESCRIPTION\n        Get user\n\n      PARAMETERS \n        id: String \u003c- Parameter comment\n\n      ERRORS\n        400 User not found\n        400 Syntax Error\n\n      RESULT\n        User\n\n      User: models.user.User(-firstName, +lastName)\n        id: String\n        lastName: String\n    \"\"\")\n    def getUser(id: String) = ...\n\n\n\n\nDefining types, not based on a class:\n\n    @no.samordnaopptak.apidoc.ApiDoc(doc=\"\"\"\n      GET /api/v1/users/{id}\n\n      DESCRIPTION\n        Get user\n\n      PARAMETERS \n        id: String \u003c- Parameter comment\n\n      ERRORS\n        400 User not found\n        400 Syntax Error\n\n      RESULT\n        User\n\n      User: !\n        id: String\n        lastName: String\n    \"\"\")\n    def getUser(id: String) = ...\n\n\n\nDefining a type with unknown number of elements:\n\n    @no.samordnaopptak.apidoc.ApiDoc(doc=\"\"\"\n      GET /api/v1/users/{id}\n\n      DESCRIPTION\n        Get user\n\n      PARAMETERS \n        id: String \u003c- Parameter comment\n\n      ERRORS\n        400 User not found\n        400 Syntax Error\n\n      RESULT\n        User\n\n      User: !\n        id: String\n        lastName: String\n        ...\n    \"\"\")\n    def getUser(id: String) = ...\n\n\n\n\nNotes\n=========\n\n* Scala classes must be specified with full path. (I.e. you have to write \"controllers.User\", not \"User\".)\n  The only exception is if the classes is in the \"models\" package. (I.e. it is possible to write \"User\" instead of \"models.User\").\n\n* In order to run validation checks on the api docs, it is necessary to call `ApiDocController.validate(\"/\")`.\n  If using specs2, it might be a good idea to put the following code (or something similar) into tests/ApiDocControllerSpec.scala:\n\n  ```scala\n    package test\n\n    import org.specs2.mutable.Specification\n    import play.api.test._\n    import play.api.test.Helpers._\n\n\n    class ApiDocControllerSpec extends Specification {\n      \"Validate swagger api docs\" in {\n          controllers.ApiDocController.validate()\n      }\n    }\n  ```\n\n  If there are end points defined in the \"routes\" file which have no api doc, you need to remove these before calling validate():\n\n  ```scala\n    class ApiDocControllerSpec extends Specification {\n      \"Validate swagger api docs\" in {\n          val routeEntries =\n             no.samordnaopptak.apidoc.RoutesHelper.getRouteEntries()\n               .filter(_.scalaClass != \"controllers.Assets\") // no api-doc for the static assets files\n          controllers.ApiDocController.validate(routeEntries)\n      }\n    }\n  ```\n\n\nLicense\n==========\n\nCopyright 2013-2014 SUN/OPSYS at University of Oslo.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at [apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favdv%2Fapi-doc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Favdv%2Fapi-doc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favdv%2Fapi-doc/lists"}