{"id":15091521,"url":"https://github.com/softwaremill/sttp-apispec","last_synced_at":"2025-04-12T06:22:30.922Z","repository":{"id":40702972,"uuid":"370649173","full_name":"softwaremill/sttp-apispec","owner":"softwaremill","description":"OpenAPI, AsyncAPI and JSON Schema Scala models.","archived":false,"fork":false,"pushed_at":"2024-04-12T13:04:41.000Z","size":452,"stargazers_count":21,"open_issues_count":13,"forks_count":8,"subscribers_count":25,"default_branch":"master","last_synced_at":"2024-04-12T16:52:08.661Z","etag":null,"topics":["asyncapi","documentation","model","openapi","scala"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/softwaremill.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}},"created_at":"2021-05-25T10:12:23.000Z","updated_at":"2024-04-15T08:43:00.355Z","dependencies_parsed_at":"2023-10-15T00:44:42.768Z","dependency_job_id":"f79c26b9-7c07-4c3a-b026-4bec65a0467e","html_url":"https://github.com/softwaremill/sttp-apispec","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softwaremill%2Fsttp-apispec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softwaremill%2Fsttp-apispec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softwaremill%2Fsttp-apispec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softwaremill%2Fsttp-apispec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/softwaremill","download_url":"https://codeload.github.com/softwaremill/sttp-apispec/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248525917,"owners_count":21118769,"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":["asyncapi","documentation","model","openapi","scala"],"created_at":"2024-09-25T10:41:35.059Z","updated_at":"2025-04-12T06:22:30.910Z","avatar_url":"https://github.com/softwaremill.png","language":"Scala","readme":"![sttp-apispec](https://github.com/softwaremill/sttp-apispec/raw/master/banner.png)\n\n[![Join the chat at https://gitter.im/softwaremill/tapir](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/softwaremill/tapir)\n[![CI](https://github.com/softwaremill/sttp-apispec/workflows/CI/badge.svg)](https://github.com/softwaremill/sttp-apispec/actions?query=workflow%3ACI+branch%3Amaster)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.softwaremill.sttp.apispec/apispec-model_2.12/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.softwaremill.sttp.apispec/apispec-model_2.13)\n\nsttp is a family of Scala HTTP-related projects, and currently includes:\n\n* [sttp client](https://github.com/softwaremill/sttp): The Scala HTTP client you always wanted!\n* [sttp tapir](https://github.com/softwaremill/tapir): Typed API descRiptions.\n* [sttp model](https://github.com/softwaremill/sttp-model): Simple Scala HTTP model.\n* sttp apispec: this project. OpenAPI, AsyncAPI and JSON Schema models.\n\n## Quickstart with sbt\n\nAdd one of the following dependencies:\n\n```scala\n// common model classes, including Schema\n\"com.softwaremill.sttp.apispec\" %% \"apispec-model\" % \"0.11.8\"\n\n// only model classes, root: OpenAPI\n\"com.softwaremill.sttp.apispec\" %% \"openapi-model\" % \"0.11.8\"\n// circe encoders for the model classes\n\"com.softwaremill.sttp.apispec\" %% \"openapi-circe\" % \"0.11.8\"\n// extension method for OpenAPI to convert to yaml\n\"com.softwaremill.sttp.apispec\" %% \"openapi-circe-yaml\" % \"0.11.8\"\n\n// only model classes, root: AsyncAPI\n\"com.softwaremill.sttp.apispec\" %% \"asyncapi-model\" % \"0.11.8\"\n// circe encoders for the model classes\n\"com.softwaremill.sttp.apispec\" %% \"asyncapi-circe\" % \"0.11.8\"\n// extension method for AsyncAPI to convert to yaml\n\"com.softwaremill.sttp.apispec\" %% \"asyncapi-circe-yaml\" % \"0.11.8\"\n```\n\nsttp apispec is available for Scala 2.12, 2.13, 3, Scala.JS and Scala Native.\n\n## Documentation\n\n[Javadocs](https://www.javadoc.io/doc/com.softwaremill.sttp.apispec/apispec-model_2.12/latest/sttp/apispec/index.html)\n\n## Usage\n\nSttp-apispec defines models and encoding/decoding logic for OpenAPI / AsyncAPI documentation.\nWhile for the most part sttp-apispec is meant to be used with [tapir](https://github.com/softwaremill/tapir) \n(where tapir converts endpoint definitions to [OpenAPI](https://tapir.softwaremill.com/en/latest/docs/openapi.html)/[AsyncAPI](https://tapir.softwaremill.com/en/latest/docs/asyncapi.html) model, \nand then sttp-apispec encodes it to desired documentation file) it can be used as a stand-alone as well in the following way:\n\n### Open API\nCurrently, OpenAPI versions 3.0.3 and 3.1 are supported, where the models are the same, \nand choosing one version over the other is a matter of selecting the proper encoder.\n\nAdd dependencies:\n```scala\n\"com.softwaremill.sttp.apispec\" %% \"openapi-model\" % \"0.11.8\"\n\"com.softwaremill.sttp.apispec\" %% \"openapi-circe-yaml\" % \"0.11.8\"\n```\n\nCreate example OpenAPI models:\n```scala\nimport sttp.apispec.openapi._\n\nimport scala.collection.immutable.ListMap\n\nval openApi3_1_0 = OpenAPI(\n  openapi = \"3.1.0\",\n  info = Info(title = \"Fruits\", version = \"1.0\"),\n  paths = Paths(ListMap(\"/\" -\u003e\n    PathItem(get = Some(Operation(\n      operationId = Some(\"getRoot\"),\n      responses = Responses(ListMap(ResponsesCodeKey(200) -\u003e Right(Response(description = \"\")))))))))\n) // define example OpenAPI 3.1.0 model\n\nval openApi3_0_3 = openApi3_1_0.openapi(\"3.0.3\") // and example OpenAPI 3.0.3 model\n```\n\nEncode it to the Open API YAML string:\n```scala\nimport sttp.apispec.openapi.circe.yaml._\n\nval yaml3_1_0 = openApi3_1_0.toYaml // converts model to OpenApi 3.1.0 yaml string\nval yaml3_0_3 = openApi3_0_3.toYaml3_0_3 // converts model to OpenApi 3.0.3 yaml string\n```\n\n### Async API\nCurrently, AsyncAPI version 2.0 is supported. \nUsage is the following:\n\nAdd dependencies\n```scala\n\"com.softwaremill.sttp.apispec\" %% \"asyncapi-model\" % \"0.11.8\"\n\"com.softwaremill.sttp.apispec\" %% \"asyncapi-circe-yaml\" % \"0.11.8\"\n```\n\nCreate an example AsyncAPI model:\n```scala\nimport sttp.apispec.asyncapi._\nimport sttp.apispec.{Schema, SchemaType}\nimport scala.collection.immutable.ListMap\n\nval asyncApi = AsyncAPI(\n  asyncapi = \"2.0.0\",\n  id = None,\n  info = Info(title = \"Fruits\", version = \"1.0\"),\n  servers = ListMap.empty,\n  channels = ListMap(\"/\" -\u003e Right(ChannelItem(\n    description = None,\n    subscribe = Some(Operation(\n      operationId = Some(\"onRoot\"),\n      summary = None,\n      description = None,\n      tags = List.empty,\n      externalDocs = None,\n      bindings = List.empty,\n      traits = List.empty,\n      message = Some(Right(SingleMessage(payload = Some(Right(Right(Schema(SchemaType.Integer))))))),\n    )),\n    publish = None,\n    parameters = ListMap.empty,\n    bindings = List.empty\n  ))),\n  components = None,\n  tags = List.empty,\n  externalDocs = None\n) //define example AsyncApi 2.0.0 model\n```\n\nEncode it to Async API YAML string:\n```scala\nimport sttp.apispec.asyncapi.circe.yaml._\n\nval yaml2_0 = asyncApi.toYaml // // convert model to AsyncApi 2.0.0 yaml string\n```\n\n## Contributing\n\nIf you have a question, or hit a problem, feel free to ask on [softwaremill.community](https://softwaremill.community/)!\n\nOr, if you encounter a bug, something is unclear in the code or documentation, don’t hesitate and open an issue on GitHub.\n\n### Building \u0026 testing the scala-native version\n\nBy default, native projects will **not** be included in the aggregate build of the root project. To include it, define the `STTP_NATIVE` environmental variable before running sbt, e.g.:\n\n```\nSTTP_NATIVE=1 sbt\n```\n\nYou might need to install some additional libraries, see the [scala native](http://www.scala-native.org/en/latest/user/setup.html) documentation site.\n\n## Commercial Support\n\nWe offer commercial support for sttp and related technologies, as well as development services. [Contact us](https://softwaremill.com) to learn more about our offer!\n\n## Copyright\n\nCopyright (C) 2022 SoftwareMill [https://softwaremill.com](https://softwaremill.com).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftwaremill%2Fsttp-apispec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftwaremill%2Fsttp-apispec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftwaremill%2Fsttp-apispec/lists"}