Swagger specification as XSD?

[Lennart Jörelid]

Hello all,

Another question from a Swagger newbie (sorry if it is somewhat on the trivial side):

Is there an XSD specification for the swagger.json file?

I reason like this:

1. Java works really well with XML and JAXB, to read and write XML (and JSON, in case one uses EclipseLink's MOXy implementation).
2. All tools/IDEs that we use in the Java/JVM development domain are really good at handling XML/XSDs, in addition to JSON. Hence, there is a swagger.xsd file defining the format, we can use our well-known toolset to generate swagger.json files (or maybe even swagger.xml files) according to a well-known and validating specificiation.

To me, this makes perfect sense - but I am well aware that I maybe overlook something due to my short exposure to swagger.

Am I missing something, or is there a swagger XSD somewhere?

[Ron Ratovsky]

 

No. There’s a JSON Schema, there’s not XSD. I see no reason to describe a JSON format using XSD (even if that’s remotely possible).

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Lennart Jörelid]

Hello Ron, and thanks for the reply.

The reason to provide an XSD format definition (in addition to the JSON schema which currently defines the swagger.json format, if I understand things correctly) is that most of the existing tooling works well with XSD - but not as well with JSON schema. For instance, I could easily use an XSD together with MOXy to generate Java classes which would synthesize a well-formed swagger.json file for me.

That - in turn - would simplify integration with a slew of tools which can operate on source code to generate swagger files.
And it would also permit a lot of simple ways to acertain that a valid swagger.json file is generated.

I perceive that Good Things (tm).
Sounds fair?

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[Ron Ratovsky]

Not quite – sounds like trying to fit a square in a triangular hole. There are plenty of tools today that utilize JSON Schema today in general, and Swagger/OpenAPI definitions specifically.

There are plenty of tools that also generate code from swagger files. Really not seeing a fit there.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[Lennart Jörelid]

Odd conclusion, there, on your part.

First -
To generate code, swagger - like JAXB - needs an in-memory metamodel used by the code generators to emit client code and documentation.
That metamodel can be defined either in code (Java seems to be chosen by swagger in its GitHub repos), or in something language agnostic like IDL, XSD or JSON Schema.

You wanna simplify for developers trying to use swagger? Then ...

• ... on the first page of the swagger documentation for developers, link to that language agnostic specification document. (Which would be https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/schemas/v2.0/schema.json if I understand correctly).
• ... on the second page, tell us how to compile the specification to java code. JAXB is well-known and mature; we know how to use it.... but JSON schema is not a part of the JDK, and I have not found any good tooling in - say - Maven to generate java sources from JSON schema. It this documented on the swagger site somewhere, which I just missed?
• Or perhaps you have a metamodel in one of the swagger repositories? Just JAXB-annotate it, and we have a very straightforward way, JDK-standard way of producing it - in addition to the JSON schema way used today.
  

Secondly -
JAXB is part of the JRE/JDK, and hence the support for XSD and XML handling is available to any project and any runtime.
It is a mature technology which works well. JSON schema is newer and not a part of the standard JDK. While there are certainly
libraries to work with it, it is certainly not as widespread in use (especially in the Java world) as XML/XSDs. Not sure I understand (at all, really)
why one schema definition language would be better than another - but I certainly would require mature and well-documented tooling.
In this respect, I would claim that XSDs and XMLs are much better integrated into documentation and tooling than JSON schema in the
java space - and hence JAXB/XSD/XML would be a good addition to swagger to simpify working with it for the java development community.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[Tony Tam]

Swagger codegen does what you're after and arguably it does a better job as it produces code for multiple languages, is easily extensible, and actively developed by a diverse community. Rather thank to to fit swagger into your paradigm, I suggest trying out this framework as it has evolved and provide feedback on that. 

Regarding the documentation, we could certainly explain better that it works "like" other formats, I agree. 

If you are bent on producing an XSD, then consider using an existing tool to go from swagger to other formats. It is possible that this work is done already in both free and open source tools. I do not, however, expect swagger to "evolve" into XSD as a first class artifact. 

I believe SoapUI does this conversion. 

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.