{"id":20234273,"url":"https://github.com/immoh/swagger-spec","last_synced_at":"2025-04-10T18:32:26.935Z","repository":{"id":62434779,"uuid":"73715609","full_name":"immoh/swagger-spec","owner":"immoh","description":"Spec for Swagger 2.0 definition ","archived":false,"fork":false,"pushed_at":"2018-03-31T06:48:51.000Z","size":93,"stargazers_count":16,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-24T16:11:11.029Z","etag":null,"topics":["clojure","clojure-spec","clojurescript","openapi","swagger","swagger2"],"latest_commit_sha":null,"homepage":"https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/immoh.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-11-14T14:59:51.000Z","updated_at":"2024-08-08T14:42:02.000Z","dependencies_parsed_at":"2022-11-01T21:00:58.929Z","dependency_job_id":null,"html_url":"https://github.com/immoh/swagger-spec","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immoh%2Fswagger-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immoh%2Fswagger-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immoh%2Fswagger-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immoh%2Fswagger-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/immoh","download_url":"https://codeload.github.com/immoh/swagger-spec/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248271853,"owners_count":21075800,"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":["clojure","clojure-spec","clojurescript","openapi","swagger","swagger2"],"created_at":"2024-11-14T08:09:33.954Z","updated_at":"2025-04-10T18:32:26.917Z","avatar_url":"https://github.com/immoh.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"# swagger-spec [![Build Status](https://travis-ci.org/immoh/swagger-spec.svg?branch=master)](https://travis-ci.org/immoh/swagger-spec) [![Dependencies Status](https://jarkeeper.com/immoh/swagger-spec/status.svg)](https://jarkeeper.com/immoh/swagger-spec)\n\nA library that contains [clojure.spec](http://clojure.org/about/spec) spec for\n[Swagger (OpenAPI) definition version 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)\n\n## Installation\n\nAdd the following dependency to your project file:\n\n```clj\n[swagger-spec \"0.5.0\"]\n```\n\n## Usage\n\nThis library registers spec `:swagger/definition` which can be used for validation and data generation.\n\nGenerally map keys are required to be keywords except in certain places where integers (status code in Responses\nObject) and strings (path in Path Items object, mime type in Example Object) can also be used. This is to make it\neasier to avoid some pitfalls with keywords (e.g. first slash is treated as namespace separator.)\n\n### Validation\n\n```clj\n(ns example\n  (:require [cheshire.core :as cheshire]\n            [clojure.spec.alpha :as s]\n            [swagger.spec]))\n\n(s/valid? :swagger/definition (cheshire/parse-string (slurp \"http://petstore.swagger.io/v2/swagger.json\") true))\n=\u003e true\n\n(s/explain :swagger/definition (-\u003e (cheshire/parse-string (slurp \"http://petstore.swagger.io/v2/swagger.json\") true)\n                                   (assoc :swagger \"2.1\")))\n;; In: [:swagger] val: \"2.1\" fails spec: :swagger.definition/swagger at: [:swagger] predicate: #{\"2.0\"}\n;; :clojure.spec.alpha/spec  :swagger/definition\n;; :clojure.spec.alpha/value ...\n```\n\n### Data Generation\n\nThe spec also allows test data to be generated for use with [test.check](https://github.com/clojure/test.check):\n\n```clj\n(ns example2\n  (:require [clojure.spec.alpha :as s]\n            [clojure.spec.gen.alpha :as gen]\n            [swagger.spec]))\n\n(binding [s/*recursion-limit* 0]\n  (first (gen/sample (s/gen :swagger/definition) 1)))\n=\u003e {:swagger \"2.0\"\n    :info {:title \"\", :version \"\", :contact {:url \"\"}, :description \"\", :termsOfService \"\"}\n    ...}\n```\n\nUnfortunately the resulting Swagger definition is 20k lines long pretty printed so I won't include it here.\nYou can view the complete definition [here](https://gist.githubusercontent.com/immoh/a12b1b0dfebf9ec41e2c4553ba062da0/raw/8407535f2344fd075814f7989991168b2239c9fa/generated-swagger-definition.clj).\n\nI would have expected `gen/sample` to generate simpler definition, especially when recursion limit is set to 0.\nThe default recursion limit of 4 causes OutOfMemoryError, the same happens if `gen/generate` is used instead\nof `gen/sample`.\n\n## Limitations\n\n* `url` field values are not validated to be in a format of a URL\n* `email` field values are not validated to be in a format of an email\n* Mime type values are not validated to be in a format of a mime type as described in\n[RFC 6838](https://tools.ietf.org/html/rfc6838)\n* HTTP Status code values are not validated as described in [RFC 7231](https://tools.ietf.org/html/rfc7231#section-6)\nand [IANA Status Code Registry](http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml)\n* `$ref` field values are not validated to be valid JSON pointers\n* Path item object `$ref` field is not validated to point to a path item object\n* `default` field value is not validated to conform to the defined data type\n* XML object `namespace` values are not validated to be in a format of a URL\n* `operationId` value uniqueness is not validated\n* `consumes` field value is not validated to be either \"multipart/form-data\", \"application/x-www-form-urlencoded\"\nor both for `file` parameters\n* Names and locations of extension fields are not validated\n* Items object allows field `description` and validates it to be a string (not in specification)\n\nThere are probably many more aspects of specification that are missing and probably many that have been misunderstood.\nSome of the validations cannot be implemented using clojure.spec.\n\n## Contributing\n\nIf you would like to implement a missing validation or fix a misunderstood one, please file a pull request\nand I'll be more than happy to merge it.\n\n## License\n\nCopyright © 2016 Immo Heikkinen\n\nDistributed under the Eclipse Public License either version 1.0 or (at your option) any later version.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimmoh%2Fswagger-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimmoh%2Fswagger-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimmoh%2Fswagger-spec/lists"}