{"id":25094423,"url":"https://github.com/felixbr/swagger-blocks-scala","last_synced_at":"2025-06-16T22:32:59.766Z","repository":{"id":44687647,"uuid":"58405935","full_name":"felixbr/swagger-blocks-scala","owner":"felixbr","description":"A library to express swagger specifications using a Scala DSL.","archived":false,"fork":false,"pushed_at":"2022-01-31T10:16:12.000Z","size":104,"stargazers_count":7,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-16T03:02:53.038Z","etag":null,"topics":["api-documentation","dsl","scala","swagger"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/felixbr.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}},"created_at":"2016-05-09T20:28:23.000Z","updated_at":"2022-01-31T10:16:16.000Z","dependencies_parsed_at":"2022-09-09T22:40:24.680Z","dependency_job_id":null,"html_url":"https://github.com/felixbr/swagger-blocks-scala","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/felixbr/swagger-blocks-scala","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felixbr%2Fswagger-blocks-scala","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felixbr%2Fswagger-blocks-scala/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felixbr%2Fswagger-blocks-scala/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felixbr%2Fswagger-blocks-scala/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/felixbr","download_url":"https://codeload.github.com/felixbr/swagger-blocks-scala/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felixbr%2Fswagger-blocks-scala/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260251798,"owners_count":22981130,"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":["api-documentation","dsl","scala","swagger"],"created_at":"2025-02-07T15:18:08.219Z","updated_at":"2025-06-16T22:32:59.721Z","avatar_url":"https://github.com/felixbr.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"# swagger-blocks-scala [![Build Status](https://travis-ci.org/felixbr/swagger-blocks-scala.svg?branch=master)](https://travis-ci.org/felixbr/swagger-blocks-scala)\n\nA library to express swagger specifications using a Scala DSL.\n\nIt is inspired mainly by [fotinakis/swagger-blocks](https://github.com/fotinakis/swagger-blocks) \nfor ruby.\n\nCurrently this only supports a part of the full swagger-spec.\n\n## Note about current maintenance status\n\nI currently have no personal use for the library anymore, so don't expect frequent updates. Personally I'd recommend either using GraphQL (which brings documentation out of the box) or using a library like [tapir](https://github.com/softwaremill/tapir) (which can generate OpenAPI definitions).\n\nFor 0.5.x onward the scope of the project was reduced, so this will hopefully help me\nkeep up with updating dependencies and the like.\n\n## Goals\n\n* Express swagger specifications in a reasonably type-safe DSL.\n* Don't clutter models and logic with annotations\n* Provide serialization for json and yaml using circe\n* Avoid reflection\n* Be reasonable to use in IDEs (e.g. IntelliJ)\n\n## Getting Started\n\n### Dependencies\n\nThe library is published on Sonatype for both `Scala 2.11.11` and `Scala 2.12.6`:\n```scala\nresolvers += Resolver.sonatypeRepo(\"releases\")\n```\n\nThere are serializers for json and yaml. The extensions also include the core lib, so\nyou only need to specify the extension you want to use:\n\n#### json (circe 0.9.3)\n```scala\n\"io.github.felixbr\" %% \"swagger-blocks-json\" % \"0.6.0\"\n```\n#### yaml (circe-yaml 0.8.0)\n```scala\n\"io.github.felixbr\" %% \"swagger-blocks-yaml\" % \"0.6.0\"\n```\n\n#### There is of course also the core module available for the DSL and core data types alone:\n```scala\n\"io.github.felixbr\" %% \"swagger-blocks-core\" % \"0.6.0\"\n```\n\n### Writing Swagger Path and Schema specifications\n    \nWrite a specification for your endpoint (e.g. in your controller's companion \nobject):\n\n```Scala\nimport swaggerblocks._\nimport swaggerblocks.Implicits._\n\nobject PetsController {\n\n  lazy val petListPath = swaggerPath(\"/pets\")(\n    operations = List(\n      operation(GET)(\n        description = \"Returns a list of pet objects\",\n        summary = \"Returns a list of pet objects\",\n\n        tags = List(\"pet\"),\n\n        parameters = List(\n          queryParameter(\n            name = \"tag\",\n            required = false,\n            schema = t.string,\n            description = \"tag to filter by\"\n          )\n        ),\n\n        responses = List(\n          response(200)(\n            description = \"pet response\",\n            schema = manyOf(petSchema)\n          )\n        )\n      )\n    )\n  )\n\n  lazy val petSchema = swaggerSchema(\"Pet\")(\n    property(\"id\")(\n      schema = t.integer\n    ),\n\n    property(\"name\")(\n      schema = t.string,\n      description = \"Name of the pet\"\n    ),\n\n    property(\"tag\")(\n      schema = t.string,\n      required = false\n    )\n  )\n\n```\n\n### Rendering the output for swagger-ui\n\nCreate a new endpoint which serves the json needed for the swagger-ui. I \nrecommend to use the same controller which serves the ui. You also have to \nwrite the required root metadata for swagger:\n\n```Scala\nimport swaggerblocks._\nimport swaggerblocks.Implicits._\nimport swaggerblocks.rendering.json.renderPretty\n\n// could be play or some other framework\nclass SwaggerController {\n\n  lazy val petstoreRoot = swaggerRoot(\"2.0\")(\n    host = \"petstore.swagger.wordnik.com\",\n    basePath = \"/api\",\n\n    info(\n      version = \"1.0.0\",\n      title = \"Swagger Petstore\",\n      description = \"A sample API that uses a petstore as an example\",\n\n      contact = contact(\n        name = \"Wordnik API Team\"\n      ),\n\n      license = license(\n        name = \"MIT\"\n      )\n    )\n  )\n\n  val paths = List(\n    PetsController.petListPath\n  )\n  val schemas = List(\n    PetsController.petSchema\n  )\n\n  def json = {\n    val swaggerJson: String = renderPretty(petstoreRoot, paths, schemas)\n\n    // response with swaggerJson as content\n  }\n}\n```\n\nNow you only have to include the new action in your `routes` file and point \na swagger-ui (possibly rendered by a standard html-view) at the url.\n\n## Usage guide\n\n### Providing a schema example\n\nSince the example has to be embedded in the final json/yaml rendering this feature depends \non the rendering library you want to use. The extension method is located at \n`swaggerblocks.extensions.\u003crenderinglib\u003e.ExampleExtension`. When is is imported, you can \ncall `.withExample` on the schema definition like shown below:\n\n```scala\nimport swaggerblocks._\nimport swaggerblocks.Implicits._\nimport swaggerblocks.extensions.json.ExampleExtension\n\nimport io.circe.syntax._\nimport io.circe.generic.auto._\n\nlazy val schemaWithExample = swaggerSchema(\"SchemaWithExample\")(\n  property(\"id\")(\n    schema = t.integer\n  ),\n  property(\"name\")(\n    schema = t.string\n  )\n).withExample(\n  Map(\n    \"id\"   -\u003e 123.asJson,     // if the values in a map are not uniform, you have to be\n    \"name\" -\u003e \"Bello\".asJson  // explicit about it being serializable (or use a case class)\n  )\n)\n\n// you can of course use all features provided by circe like\n// case class serialization\n\ncase class Dog(id: Int, name: String)\n\nlazy val schemaWithCaseClassExample = swaggerSchema(\"SchemaWithCaseClassExample\")(\n  property(\"id\")(\n    schema = t.integer\n  ),\n  property(\"name\")(\n    schema = t.string\n  )\n).withExample(\n  Dog(123, \"Fiffi\")\n)\n```\n\n## Caveats\n\nWhile for the most part the library API tries to stick to the swagger spec, \nthere are some exceptions made either for technical reasons, type-safety or \nusability:\n\n* Since `type` is a restricted keyword you'll have to use `schema` in its place. \nYou can use primitive types (e.g. `schema = t.string`) as well as references to schemas \n(e.g. `schema = petSchema`) and it will be sorted out behind the scenes.\n* Many values in swagger can either be a primitive type, an object or a list of \nthe former two. In order to make this more type-safe \nand usable, there is a `manyOf` helper for lists, which accepts primitive types \nor schemas.\nBecause of type erasure you have to use `parameter.manyOf` instead of just `manyOf` for \nall non-body parameters.\n* Types are currently namespaced by `t` (e.g. `t.string`, `t.integer`, `t.number`). \nSome types should only be used in certain places according to the swagger spec. \nFor example `t.file` is not allowed in path-parameters, but currently this is not enforced. \nThere are namespaces for the different parameters, so you can easily find the allowed \nones using autocompletion (e.g. `t.parameter.path.string` or `t.parameter.formData.file`).\n* The DSL uses a few implicit conversions to provide an easier and more uniform way to write things.\nFor example most optional text fields like `description` still accept a `String` literal \ndue to an implicit `String =\u003e Option[String]`. The other conversions deal with differences \nin `schema` fields.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelixbr%2Fswagger-blocks-scala","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffelixbr%2Fswagger-blocks-scala","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelixbr%2Fswagger-blocks-scala/lists"}