I have to maintain a project that uses Swagger to codegen the api interface. Looking at the model.mustache, I see this:
{{#models}}
{{#model}}{{#description}}
/**
* {{description}}
**/{{/description}}
and a bunch of other keywords like enum, defaultValue, vars, package, etc. Where do these come from? I've been scouring the internet trying to find swagger documentation on this but I cannot find anything. Lots of the links that refer to swagger info on github return 404 pages. In the end, what I want to be able to do is to have a property exist in my actual .json file that swagger is using to generate the interfaces and models to conditionally generate code. I saw that there is the
{{#property}}{{/property}}
{{^property}}{{/property}}
notation for if/else statements, but it doesn’t work on any property of my own .json. For example, in my json I have an id field. So if I wanted to do a contrived example
{{#id}}System.out.println(“test test”);{{/id}}
won’t work because swagger does not recognize the id tag. So my question is, can I add these tags?
there are lots of tools to help out. If you see broken links, please submit issues to the swagger-codegen project.
As of 2.1.x-M1, swagger-codegen has a very helpful "debug" mode which lets you list all the possible values for your environment. You can invoke it as follows:
java -DdebugModels -jar {path-to}/swagger-codegen-cli.jar generate {opts}
The supported debug flags are:
-DdebugModels: outputs the variables for each model discovered by codegen
-DdebugOperations: outputs the variables for each operation
-DdebugSupportingFiles: shows supporting file data (anything but models or operations)
-DdebugSwagger: shows the parsed swagger representation
I do see that these are missing from the README. Will make sure they get added.
Related
Is there a way to generate a README.md file from swagger? I would like to put similar details that would be found in swagger web page plus some custom comments.
Also, is there a way to make a aggregator swagger web page? I want to have the all swagger web pages from all micro services also in a single place. This could enable me to take higher picture notion of my system and maybe do some queries like "how
many ways certain entity can get this another entity?".
Regarding README.md file - not sure what information you want to include in it, but you can write your own method which will do it using Swagger Parser in order to get required information from Swagger specification.
Regarding aggregated swagger - you can use Swagger-aggregate for this purpose.
I hope my question is not too broad.
Our application has an Angular frontend and a Java backend and
we need both frontend and backened validation. At the moment, we manually code
validators in Typescript and Java that basically do the same thing.
Since that is not only tedious but also error-prone, we would like to define once (maybe in a JSON file)
which input fields have which constraints and ideally use a piece of software that auto-generates
Java and Typescript code based on that definition.
My question is: are there any open-source/commercial software solutions that take care of this?
It seems like a common enough problem, but I haven't come across
a proper solution yet. JSON schema seemed promising and since we're using swagger
anyway, I'd hoped that swagger-codegen would automatically take the supported JSON-schema keywords as constraints into account,
but I haven't figured out how it works. When I generate Angular code, constraints such as 'minimum' and 'maximum' are completely ignored,
and when I generate Java SpringBoot code, they only show up as annotations.
This is exactly what JSON Schema is designed for. Open API (swagger) modifies JSON Schema for it's own purposes, which doesn't include validation.
JSON Schema has validator implementations in most major languages allowing you to use the same schema to do the same validation on the front end and the back end. http://json-schema.org/implementations.html
Unfortunately, you likely won't be able to use the same schemas you use for your Open API service definition. I'm not aware of any validator implementations that support Open API's flavor of JSON Schema. I understand that Open API is trying to close the gap between their definition and JSON Schema, but a gap still exists.
It is very easy for Swagger annotations to drift away from the actual code.
E.g.
I could change the return from Response.ok to Response.created and easily forget to update the annotations from 200 to 201.
Or I could change what is valid as null or not null and the end user will get confusing rejection messages even though their payload matches exactly what the documentation says.
How do I test that my swagger documentation matches what my code is doing?
A test that uses selenium and phantomjs to parse the swagger-ui web page?
Reflection to parse the annotations?
Get the generated swagger.json and parse it?
Something else?
Unfortunately I can't switch to Spring REST Docs.
You can check the following library which contains a couple of projects that deal with API validation. I think the one you're looking for is called "swagger-request-validator-mockmvc", but you might find the other libraries useful as well.
Good luck.
I'm having difficulty attempting to explain what I mean but here I go..
I am looking for a configuration parser that does the following..
Allows me to configure REQUIRED settings and if they are not set then the program should not start.
Allow users to define as many 'custom settings' as they need. So for example, say you want to add some sort of redirect to the configuration, I'd like it to look like this.
redirect-1: 100->200
And that would hopefully 'redirect' 100 to 200. I would obviously build this logic into my program, but is there a library that will read sequential settings like redirect-1, redirect-2, etc. until it reaches the EOF? Hopefully I'm making sense.
I think what you are looking for is a configuration file parser that also provides a "schema validation" engine. Within the syntax of the schema validation language, you would specify which configuration variables are required (and their types), so the validation engine could verify that those variables are present and have values that comply with their types (for example, "42" is a valid integer, but "hello, world" is not).
XML has several competing schema validation languages, including XML Schema and RELAX NG. If you look on Amazon, you can find books on those.
JSON also has its own schema validation language.
The only other configuration language with its own schema validation language I can think of Config4*, which is one that I developed. If you want to read more about Config4*, then I suggest you read Chapters 2 and 3 of the Config4* Getting Started Guide (PDF and HTML) to get an overview of its syntax and API. Then skip to Chapter 9 to find full details of its schema validation language. The ignore rules (discussed in Section 9.2.6) can be used to specify that the schema validation engine should ignore some configuration variables/scopes.
I've tried any number of searches looking for an actual definition/description of just what is legal as a Spring form path and I cannot find anything. i.e.
<form:select path="What can I put here?">.
The closest I've been able to find is the table on this page:
http://docs.spring.io/spring/docs/2.5.x/reference/validation.html
Table 5.1 gives "examples", but they are only examples.
I really am looking for a definitive explanation of exactly what is legal in a Spring path and also whether any of those are limited to certain versions. I realize this is edging close to asking for favorite off-site resources but I'm looking for the information or links to the official documentation that covers this, not random tutorials, so it should be on topic. I can find plenty of tutorials online but I'm looking for complete reference not a basic introduction.
I'm working on a project using spring-core-2.5.3.jar, I'd really like to find out what is possible in that version although having reference material for more current Spring versions would be good too. I don't know how possible it will be to get an upgrade of Spring done on this project unfortunately.
To be clear - I'm aware that you can access the property String getFoo() using the path "foo". That in some versions of Spring (which?) you can access the first element of String[] getBar() using "bar[0]", etc.
But what are the limitations on this, are there any other things you can do?
Does it support maps and sets?
If it's a complex thing like Map<String,List[Integer]> oof can you do oof["test"][3] as the path?.
Basically the path supports a lot more than just the simple property reading but I can't find anything telling me just what the options and limitations are. Rather than just trying things and seeing what works and hoping I think of everything I'd really like to have a comprehensive list of some kind showing me just what my options are.
Its the reference to the comand object property you want to reference by that field
so if its MyCommand.getCheddar()
you write "cheddar" in path. This is part of spring-mvc, not core spring. It uses the standard convention