I'd like to make some customizations in models layouts, or at least add some comments.
Here is how it looks like by default:
I use java springfox for swagger UI.
Here is my Swagger config:
Is it possible to do that?
It seems to me that you are looking for #ApiModelProperty. You can annotate each attribute with it and include value parameter as the description. Additional details at https://www.baeldung.com/swagger-apiparam-vs-apimodelproperty.
#ApiModelProperty(value = "Your description")
int fromLocation;
Related
For example there are two classes with same name Group in different packages.
But when referring to models in swagger ui only one model is being shown and even the response mapping is not proper, swagger is incorrectly referring to these models.
Yes. Adding the below property solves this issue.
springdoc.use-fqn=true
But after adding this, the schemas in swagger ui start showing up with the complete package name. To avoid this try annotating your model classes with:
#Schema(name = "class name to be displayed")
I meet the same problem today with springdoc-openapi-ui:1.5.9, and maybe solved it.
Simply add key-value pairs to application.properties.
springdoc.use-fqn=true
Then org.springdoc.core.SpringDocConfigProperties read this value, and pass it to io.swagger.v3.core.jackson.TypeNameResolver.
We are using Swagger to model our API with Spring annotations:
#Operation(summary = "Creates a post for given user.")
#PostMapping("/post")
open fun createPost(
#RequestParam("userId") user: User,
)
The issue we are having is that Swagger does not know there is a logic behind and we are only passing userId: Long for which the user is loaded by Hibernate.
The model of User contains several #OneToOne, #ManyToOne, #OneToMany relations to other entities and Swagger builds the model of User with all of them. This causes the model to be huge and some of our Swagger docs wouldn't even load in the browser as the model is in the size of megabytes.
Is there a way to tell Swagger:
to ignore specific entity/entities
to enforce different type (in this case Long)
Ideally something like:
#Operation(summary = "Creates a post for given user.")
#PostMapping("/post")
open fun createPost(
#SwaggerType(Long::class)
#RequestParam("userId")
user: User,
)
The cleanest way is to use Springfox with an alternate type rule. See no 10 in the examples given here:
https://springfox.github.io/springfox/docs/current/#springfox-spring-mvc-and-spring-boot
This enables you to completely replace your User class by any other (fake) class that you want to show to the Swagger user, without polluting your model with workarounds - but still staying transparent in your code.
There are a few options that can be tried:
Using inheritance with User Model, you can just define a SuperClass-childClass mapping with User class only containing the userId, and the child class that inherits from it will be holding the other attributes for you. In this way, the input will only be the userId with minimal effort.
Using JsonIgnore, but this works really well while returning the response.
With OpenAPI, Swagger has introduced the capability to use specific properties from the request class. More can be read from
https://swagger.io/docs/specification/describing-request-body/
you can use two different class,a basic class and a senior class,and the senior extends the basic,use basic class in API;
or you can use #JsonIgnore if you don't want to show the field ,like:
#JsonIgnore
private String name;
Beacuse Swagger use jackson to json, if you shield the field by jackson,it will not appear.
In swagger
you can use #ApiModelProperty(hidden = true),This is the perfect way
In Swagger model / Example value, I see this sample value for a $date-time field.
"lastModifiedDate": "2020-07-09T12:50:48.461Z"
But I have defined this field like this
#JsonFormat(pattern = "yyyy-MM-dd'T'HH:mm:ss.SSSXXX", timezone="America/New_York")
private Date lastModifiedDate;
So the actual values returned by my API look like this:
"lastModifiedDate": "2020-07-09T07:44:35.366-04:00"
So I am not sure why swagger is not detecting this.
Probably because this JsonFormat is a Jackson annotation.
com.fasterxml.jackson.annotation.JsonFormat
So... do I need to add some additional Swagger annotation here?
I don't have a Swagger descriptor file (or don't have control over it),
I have just annotations in the Java code.
Can this be done via annotations?
I think that the annotation required for documenting your moddel is #ApiModelProperty, take a look on it http://docs.swagger.io/swagger-core/current/apidocs/io/swagger/annotations/ApiModel.html
hope it will be helpfull.
Does anyone know if it's possible to create an example post body with pre-populated/default values from Java annotations? My goal is for users to have a working example when viewing a POST endpoint in Swagger UI. Ideally this working example is created from annotations in the code.
For Example on a model object property:
#ApiModelProperty(example = "http://istock.com/my_cool_image")
#JsonProperty("submitted-image-url")
private String submittedImageUrl;
Would produce something like this in Swagger UI (note the example URL shows up in the Model Schema):
The way it appears to be designed, you have to click on Example Value under Data Type for the request/Value textarea to be populated (at least in Swagger 1.5.9).
How can I use my own annotation for building swagger ui page.
For example I defined annotation and use it:
#PUT
#MyOwnAnnotationForAdditionalPropInSwagger(value = "Some text")
#Path( "/{carId}" )
#Consumes(MediaType.APPLICATION_JSON)
#Produces(MediaType.APPLICATION_JSON)
#ApiOperation(
value = "Updates car info"
)
public Response patchItem(#ApiParam(value = "Fields to update") Car item) {
/*some code*/
}
After that probably I should extend some class from swagger-core and specify to scan my annotation (#MyOwnAnnotationForAdditionalPropInSwagger).
As result I want to see additional column in swagger ui with my text.
How I can realize it? What class I need to extend?
The swagger 2.0 supports custom fields, there was a Pull Request for this back in 2013 (https://github.com/swagger-api/swagger-node/pull/47).
While apparently it's easy to add the custom fields, since they are not present in the Swagger 2.0 spec, Swagger-UI won't display them by default.
For this to work you will have to change a couple of things.
Implement the desired annotation in your parser implementation (ie. swagger-core or swagger-php) if it doesn't exist.
Clone and modify swagger-ui to display your custom field as you wish.
Note that by doing this you will in fact violate the swagger json schema (https://github.com/swagger-api/swagger-spec/blob/master/schemas/v2.0/schema.json) and any third party validators you may use will fail.
I believe what you are trying to do ca be achieved extending the swagger core reader as described in swagger documentation. Here is an example in one of my projects.