# Using swagger with jsonapi definitions? **URL:** \ **Category:** Uncategorized\ **Created:** [March 22, 2016, 11:11pm UTC](https://discuss.jsonapi.org/t/using-swagger-with-jsonapi-definitions/400 "2016-03-22T23:11:05Z")\ **Posts on this page:** 13\ **Page:** 1
**Author:** ![reece](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/reece/32/246_2.png) [@reece](https://discuss.jsonapi.org/u/reece)\ **Post date:** [March 22, 2016, 11:11pm UTC](https://discuss.jsonapi.org/t/using-swagger-with-jsonapi-definitions/400/1 "2016-03-22T23:11:05Z")
I’m planning to use jsonapi conventions for a REST API designed and documented with swagger. Although I _could_ inline the jsonapi definitions there (e.g., for error, meta, etc), it would seem better to reference them in an external doc. First, does that sound right? Second, has anyone done this? If so, any tips? Do I need a yaml version of the schema, or will [http://jsonapi.org/schema](http://jsonapi.org/schema) work as-is? Thanks, Reece ---
**Author:** ![jlangley](https://avatars.discourse-cdn.com/v4/letter/j/9e8a1a/32.png) [@jlangley](https://discuss.jsonapi.org/u/jlangley)\ **Post date:** [March 24, 2016, 5:12pm UTC](https://discuss.jsonapi.org/t/using-swagger-with-jsonapi-definitions/400/2 "2016-03-24T17:12:08Z")
> will [http://jsonapi.org/schema5](http://jsonapi.org/schema5) work as-is? No. Swagger doesn’t support the full set of JSON-Schema attributes (e.g. “oneOf” is not supported) 😞 ---
**Author:** ![frankie](https://avatars.discourse-cdn.com/v4/letter/f/258eb7/32.png) [@frankie](https://discuss.jsonapi.org/u/frankie)\ **Post date:** [May 16, 2016, 5:11am UTC](https://discuss.jsonapi.org/t/using-swagger-with-jsonapi-definitions/400/3 "2016-05-16T05:11:20Z")
@reece were you able to solve this? @jlangley, can you help me with this… We also have a requirement to document our JSON API using Swagger. Can you give couple of samples as to how to achieve this. Suppose if I have article model (from [jsonapi](http://jsonapi.org/) with attributes **title** and relationships **author** and **comments** and couple of endoints, /api/articles (which returns paginated articles) and /api/articles/1 which returns a single article, how should the **swagger models** look like? What should be the response model for the above endpoints? How should sideloading (include=authors,comments) be represented in swagger responses? ---
**Author:** ![halfar](https://avatars.discourse-cdn.com/v4/letter/h/ad7895/32.png) [@halfar](https://discuss.jsonapi.org/u/halfar)\ **Post date:** [May 3, 2017, 7:34pm UTC](https://discuss.jsonapi.org/t/using-swagger-with-jsonapi-definitions/400/4 "2017-05-03T19:34:18Z")
Hi Reece , did you managed a way to make this works ? i have similar situation, i am using a python frameworks that supports json API and i need to add a swagger documentation for my APIs. ---
**Author:** ![reece](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/reece/32/246_2.png) [@reece](https://discuss.jsonapi.org/u/reece)\ **Post date:** [May 3, 2017, 8:22pm UTC](https://discuss.jsonapi.org/t/using-swagger-with-jsonapi-definitions/400/5 "2017-05-03T20:22:31Z")
I gave up on jsonapi with swagger/openapi. OpenAPI 3 (not yet released) claims to support a few more of the json schema elements, including oneOf. I’m unsure whether that’s enough to enable jsonapi. Also, bear in mind that tools to actually use OpenAPI 3 will naturally lag that release. I would love to see full convergence of openapi, json schema, and jsonapi, with a good example! ---
**Author:** ![michaelhibay](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/michaelhibay/32/405_2.png) [@michaelhibay](https://discuss.jsonapi.org/u/michaelhibay)\ **Post date:** [May 3, 2017, 9:15pm UTC](https://discuss.jsonapi.org/t/using-swagger-with-jsonapi-definitions/400/6 "2017-05-03T21:15:22Z")
> [@reece](#): > > I would love to see full convergence of openapi, json schema, and jsonapi, with a good example! JsonApi and hypermedia as a whole are orthogonal to OAS/Swagger fundamentally. It is very simple, the foundational element of the OAS specification is the path, and while in hypermedia APIs it is the vocabulary of the hypermedia. Some elements could be incorporated, but there is no way to fundamentally map one to another without changes to either of those basic properties. ---
**Author:** ![g\_montel](https://avatars.discourse-cdn.com/v4/letter/g/258eb7/32.png) [@g\_montel](https://discuss.jsonapi.org/u/g_montel)\ **Post date:** [October 4, 2017, 8:30am UTC](https://discuss.jsonapi.org/t/using-swagger-with-jsonapi-definitions/400/7 "2017-10-04T08:30:20Z")
Hello there ! Same here. I need to document a JSON API compliant API with Swagger 3 / Open API. Does anybody know if it’s feasible ? Thanks ! Geoffroy ---
**Author:** ![michaelhibay](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/michaelhibay/32/405_2.png) [@michaelhibay](https://discuss.jsonapi.org/u/michaelhibay)\ **Post date:** [October 4, 2017, 4:03pm UTC](https://discuss.jsonapi.org/t/using-swagger-with-jsonapi-definitions/400/8 "2017-10-04T16:03:13Z")
Sorry Geoffroy, but water (Hypermedia) and oil (OAS 3) still don’t mix. They are fundamentally intractable as currently designed. ---
**Author:** ![g\_montel](https://avatars.discourse-cdn.com/v4/letter/g/258eb7/32.png) [@g\_montel](https://discuss.jsonapi.org/u/g_montel)\ **Post date:** [October 4, 2017, 4:35pm UTC](https://discuss.jsonapi.org/t/using-swagger-with-jsonapi-definitions/400/9 "2017-10-04T16:35:24Z")
Too bad ! Does anybody know any alternative to nicely document a JSON API ? ---
**Author:** ![michaelhibay](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/michaelhibay/32/405_2.png) [@michaelhibay](https://discuss.jsonapi.org/u/michaelhibay)\ **Post date:** [October 4, 2017, 4:56pm UTC](https://discuss.jsonapi.org/t/using-swagger-with-jsonapi-definitions/400/10 "2017-10-04T16:56:28Z")
My favorite is an ALPS profile combined with a JSON Home document. This allows a simple browser to be implemented (link HAL Browser) for documentation exploration and sandboxing. ---
**Author:** ![reece](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/reece/32/246_2.png) [@reece](https://discuss.jsonapi.org/u/reece)\ **Post date:** [February 12, 2019, 12:41am UTC](https://discuss.jsonapi.org/t/using-swagger-with-jsonapi-definitions/400/11 "2019-02-12T00:41:40Z")
For those who come this way again, here are two links are closer to what I was looking for. > **[Not found - Bendyworks: We Make Web and Mobile Apps](https://bendyworks.com/404)** > > We design and build software that stands the test of time, specializing in Ruby on Rails, React, and Ionic. > External references now work in the tools that I use, so it seems likely that one can centralize the json api schema definitions to be used within an openapi schema. ---
**Author:** ![neolu](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/neolu/32/616_2.png) [@neolu](https://discuss.jsonapi.org/u/neolu)\ **Post date:** [April 27, 2019, 3:20am UTC](https://discuss.jsonapi.org/t/using-swagger-with-jsonapi-definitions/400/12 "2019-04-27T03:20:12Z")
i write a `jsonapi-swagger` generator use [rswag](https://github.com/domaindrivendev/rswag). github: [https://github.com/superiorlu/jsonapi-swagger](https://github.com/superiorlu/jsonapi-swagger) ---
**Author:** ![neolu](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/neolu/32/616_2.png) [@neolu](https://discuss.jsonapi.org/u/neolu)\ **Post date:** [June 19, 2019, 6:44am UTC](https://discuss.jsonapi.org/t/using-swagger-with-jsonapi-definitions/400/13 "2019-06-19T06:44:30Z")
hi, i have updated jsonapi-swagger gem. you can generate a swagger.json through json resource and browse doc through swagger ui . github: [https://github.com/superiorlu/jsonapi-swagger](https://github.com/superiorlu/jsonapi-swagger)