{"id":21948127,"url":"https://github.com/evolution-gaming/akka-http-documenteddsl","last_synced_at":"2025-04-23T00:16:29.119Z","repository":{"id":14108775,"uuid":"76019714","full_name":"evolution-gaming/akka-http-documenteddsl","owner":"evolution-gaming","description":"Autodocumented Directives fo akka-http.","archived":false,"fork":false,"pushed_at":"2024-07-29T13:53:38.000Z","size":173,"stargazers_count":17,"open_issues_count":11,"forks_count":3,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-23T00:16:22.372Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evolution-gaming.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-12-09T09:09:21.000Z","updated_at":"2024-07-18T15:55:04.000Z","dependencies_parsed_at":"2024-07-21T13:34:03.592Z","dependency_job_id":null,"html_url":"https://github.com/evolution-gaming/akka-http-documenteddsl","commit_stats":null,"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evolution-gaming%2Fakka-http-documenteddsl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evolution-gaming%2Fakka-http-documenteddsl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evolution-gaming%2Fakka-http-documenteddsl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evolution-gaming%2Fakka-http-documenteddsl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evolution-gaming","download_url":"https://codeload.github.com/evolution-gaming/akka-http-documenteddsl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250343960,"owners_count":21415042,"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-11-29T05:12:07.657Z","updated_at":"2025-04-23T00:16:28.965Z","avatar_url":"https://github.com/evolution-gaming.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AKKA-HTTP-DOCUMENTEDDSL\n\n[![CI](https://github.com/evolution-gaming/akka-http-documenteddsl/workflows/CI/badge.svg)](https://github.com/evolution-gaming/akka-http-documenteddsl/actions?query=workflow%3ACI)\n[![Coverage Status](https://coveralls.io/repos/github/evolution-gaming/akka-http-documenteddsl/badge.svg)](https://coveralls.io/github/evolution-gaming/akka-http-documenteddsl)\n[![version](https://api.bintray.com/packages/evolutiongaming/maven/akka-http-documenteddsl/images/download.svg) ](https://bintray.com/evolutiongaming/maven/akka-http-documenteddsl/_latestVersion)\n\n## The Problem\n Want to provide [Swaggerrish](http://swagger.io/) api documentation of your app? Or [RAML](http://raml.org/)?\n \n [Spray](http://spray.io) and [Akka-Http](http://doc.akka.io/docs/akka-http/current/scala.html) both have perfect routing dsl and at the first sight it will be easy to extract\n the data to build something like swagger on top of it. But looking deeper you see that these was designed\n being not introspective. In short you are unable to distinguish one directive from another\n in runtime (or in compile time using macros) and therefore you can't build the picture of your route behaviour.\n \n So not Spray nor Akka-Http have any mechanisms to extract documentation from their routing dsl.\n \n## Provided Solution\n For our needs we selected number of directives which could form the api documentation\n and wrapped them into neatly documented directives. We then added a few of our own directives\n to make us able to describe specifics of our apis and now we are able to generate some internally\n invented format describing our api. It is not a Swagger or a Raml, it is something simpler but still\n rich enough to provide users with all the needed information about api. Generated documentation then could be\n available in json form, and/or presented via html5 frontend.\n \n### Introduction\n To use documented directives you need to import couple things.\n```scala\nimport akka.http.documenteddsl.DDirectives._\n```\n This is an entry point to documented dsl.\n \n\u003e Next important thing - you need to have _org.coursera.autoschema.AutoSchema_ which could be accessed implicitly in your scope.\n\n There are number of documented directives:\n - Method directives\n   - GET\n   - POST\n   - PUT\n   - DELETE\n   - HEAD\n   - OPTIONS\n - Path directives\n   - Path\n - Header directives\n   - Header\n   - OptHeader\n - Parameter directives\n   - Param\n   - OptParam\n   - DefaultParam\n - Form directives\n   - FormField\n   - OptFormField\n   - DefaultFormField\n - Marshalling directives\n   - In\n - Unmarshalling directives\n   - Out\n - Session directives\n   - Session\n - Documentation directives\n   - Category\n   - Title\n   - Description\n\n  Here are some primitive example of how your code may look like if using documented dsl.\n\n```scala\nimplicit object autoSchema extends AutoSchema with DocumentedTypeMappings\n\nprivate val Find    = Category(\"Api\", \"Resource\") \u0026 Title(\"Find\") \u0026 Description(\"Returns specified resource entrie\") \u0026\n                      Path(Segment[String]) \u0026 GET \u0026\n                      Out[ExampleResource] \u0026 Out(StatusCodes.NotFound, \"Resource not found\")\n\nprivate val FindAll = Category(\"Api\", \"Resource\") \u0026 Title(\"Find All\") \u0026 Description(\"Returns all resource entries\") \u0026\n                      GET \u0026\n                      Out[Set[ExampleResource]]\n\nprivate val Create  = Category(\"Api\", \"Resource\") \u0026 Title(\"Create\") \u0026 Description(\"Creates a new resource entry\") \u0026\n                      POST \u0026\n                      In(CreateExample) \u0026 Out[ExampleResource]\n\nprivate val Update  = Category(\"Api\", \"Resource\") \u0026 Title(\"Update\") \u0026 Description(\"Updates specified resource entry\") \u0026\n                      Path(Segment[String]) \u0026 PUT \u0026\n                      In(UpdateExample) \u0026 Out[ExampleResource] \u0026 Out(StatusCodes.NotFound, \"Resource not found\")\n\nprivate val Delete  = Category(\"Api\", \"Resource\") \u0026 Title(\"Delete\") \u0026 Description(\"Deletes specified resource entry\") \u0026\n                      Path(Segment[String]) \u0026 DELETE \u0026\n                      Out[ExampleResource] \u0026 Out(StatusCodes.NotFound, \"Resource not found\")\n\nlazy val route: DRoute = PathPrefix(\"resources\") {\n  Find    {find} |~|\n  FindAll {complete(collection)} |~|\n  Create  {create} |~|\n  Update  {update} |~|\n  Delete  {delete}\n}\n\nimport akka.http.scaladsl.server.Route\nimport akka.http.scaladsl.server.Directives._\n\nprivate def find(id: String): Route = ???\nprivate def create(payload: CreateResource): Route = ???\nprivate def update(id: String, payload: UpdateResource): Route = ???\nprivate def delete(id: String): Route = ???\n```\n\n And here is the documentation generated from this example\n```json\nGET http://localhost:8080/api.json\n\n{\n  \"routes\" : [ {\n    \"uid\" : \"14906C3B966588C5BAD6B46E\",\n    \"method\" : \"GET\",\n    \"path\" : \"resources\",\n    \"out\" : {\n      \"success\" : [ {\n        \"status\" : {\n          \"code\" : 200,\n          \"detail\" : \"OK\"\n        },\n        \"contentType\" : \"application/json\",\n        \"schema\" : {\n          \"type\" : \"array\",\n          \"items\" : {\n            \"title\" : \"ExampleResource\",\n            \"type\" : \"object\",\n            \"required\" : [ \"name\", \"id\" ],\n            \"properties\" : {\n              \"description\" : {\n                \"type\" : \"string\"\n              },\n              \"id\" : {\n                \"type\" : \"string\"\n              },\n              \"name\" : {\n                \"type\" : \"string\"\n              }\n            }\n          }\n        }\n      } ],\n      \"failure\" : [ ]\n    },\n    \"title\" : \"Find All\",\n    \"description\" : \"Returns all resource entries\",\n    \"category\" : [ \"Api\", \"Resource\" ]\n  }, {...} ]\n}\n```\n\n Default DocumentationRoutes also provide the way to decouple routes requests.\n You use OPTIONS to request api toc. And then you can request route by route using uids.\n```json\nOPTIONS http://localhost:8080/api.json\n\n{\n  \"Api\": {\n    \"Resource\": {\n      \"uid\": {\n        \"14906C3B8B40240130BFA42E\": \"Delete\",\n        \"14906C3B95EB76C2E1EA5DEE\": \"Update\",\n        \"14906C3B96287FC336629FAE\": \"Create\",\n        \"14906C3B965646849338300E\": \"Find\",\n        \"14906C3B966588C5BAD6B46E\": \"Find All\"\n      }\n    }\n  }\n}\n\nGET http://localhost:8080/api.json/14906C3B8B40240130BFA42E\n\n{\n  \"uid\" : \"14906C3B966588C5BAD6B46E\",\n  \"method\" : \"GET\",\n  \"path\" : \"resources\",\n  \"out\" : {\n    \"success\" : [ {\n      \"status\" : {\n        \"code\" : 200,\n        \"detail\" : \"OK\"\n      },\n      \"contentType\" : \"application/json\",\n      \"schema\" : {\n        \"type\" : \"array\",\n        \"items\" : {\n          \"title\" : \"ExampleResource\",\n          \"type\" : \"object\",\n          \"required\" : [ \"name\", \"id\" ],\n          \"properties\" : {\n            \"description\" : {\n              \"type\" : \"string\"\n            },\n            \"id\" : {\n              \"type\" : \"string\"\n            },\n            \"name\" : {\n              \"type\" : \"string\"\n            }\n          }\n        }\n      }\n    } ],\n    \"failure\" : [ ]\n  },\n  \"title\" : \"Find All\",\n  \"description\" : \"Returns all resource entries\",\n  \"category\" : [ \"Api\", \"Resource\" ]\n}\n```\n\n Project contain small api example built on documented directives to show you how does it look like.\n [Please take a look at it](https://github.com/evolution-gaming/akka-http-documenteddsl/src/examples/scala).\n  \n### Known issues\n - Only Play Json supported now\n - Your payloads always treated as json payloads\n - Lack of ability to describe route hierarchically (it is possible only for Directive0, so you still can prefix your routes)\n \n## Setup\n**Sbt**\n```scala\nresolvers += Resolver.bintrayRepo(\"evolutiongaming\", \"maven\")\nlibraryDependencies += \"com.evolutiongaming\" %% \"akka-http-documenteddsl\" % \"_latestVersion\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevolution-gaming%2Fakka-http-documenteddsl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevolution-gaming%2Fakka-http-documenteddsl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevolution-gaming%2Fakka-http-documenteddsl/lists"}