Raghuraman Ramaswamy

Currently there are two well known strategies. Design first and Code first. Both have pros and cons and both have earned their place. There is no absolute stand on which is better. Its a long debate. I have tried both extensively and even variations- story for another time. What I would recommend is try everything and use what you feel is best for your purpose. Since you like design first have a look at my article on ping federate too. And thanks.

I too am a fan of Maven. I am also a fan of Ant. I have used Gradle. Its definitely harder to get right with it sometimes. For most projects I will certainly prefer Maven. If in a project I need both maven and some additional setup automation for example will use ant. (Ansible anyone?) But its in that scenario if I need to use Maven and lots of ant targets manually and give them to developers for running them step by step one by one. In that one scenario I would prefer gradle with Ant. The users can use gradle as the single interface and get the setup steps as well as the project build done even though under the hood both gradle and ant are used.

Nice useful article.

Liked your style. Very Eloquent.

Hi Malte,

Am glad the article was of some help.

Not sure what you meant by "Resolver is called multiple times with and without a parent Schema ".

Are you referring to applyBeanValidatorAnnotations method in CustomOpenApiValidator extends ModelResolver {}.

Its just a method where in its parent class - super method -you will see how the standard validator annotations have been similarly queried and added to swagger documentation for each property.

In my demo I do the same thing using same derived method. Just using swagger schema extensions to convey the constraints because the base method and existing means allow only so much.

I hope therefore you will agree the method has been used in a manner consistent with its original intent and demonstrated the purpose of my article..

Raghu

Hi,

Thanks for the comment. Undoubtedly there are multiple ways to achieve this.

Main point that I am showing here is how other validation annotations including custom annotations - which springdoc/swagger cannot be even aware of - can be queried to create tighter contracts and communicate the constraints more thoroughly using swagger schema extensions.

I would encourage the readers to explore every extensibility offered by springdoc and swagger.

Edit added later: On my part I have tried to use the appropriate API methods according to its original intent.

Raghu

You are right that I did not use the SpringDoc maven plugin because its not needed for the purpose of this article. There are a few other topics including the spring doc maven plugin and its proper usage- I will try writing about them in future.

Cors is for say angular or other ui applications that might be invoking your java back end -assuming the ui application and back-end are separate applications. Cors is not for swagger ui -assuming its getting generated from the back end application.

What you probably need is to configure appropriate access for the swagger urls.

Maybe you can use this for starting point:

http.authorizeRequests().antMatchers("/swagger-ui.html","/swagger-ui/**", "/v3/**" ).permitAll();

Also keep in mind sequencing of these commands is important assuming there are other such configurations.

OK. Thought it was something you needed to figure out. Great.

Hope you are using the new

<dependency>

<groupId>org.springdoc</groupId>

<artifactId>springdoc-openapi-ui</artifactId>

<version>1.3.6</version>

</dependency>

If so the message will be corresponding to HttpStatus code.

In the controller advice method ensure the @ResponseStatus(code) matches what you are returning in ResponseEntity() in the controller advice method.

Do not populate ResponseStatus's reason attribute. Its been know to cause problems.

Beyond that bunch of generic advice see if for any reason the controller advice method is getting skipped. What is the actual exception in the logs. A little debugging will be needed. Do you need a new handler method based on what you see in the logs. Is some other handler handling the exception.

I will be a bit more specific. There are some standard i would call them framework exceptions. You can find them referred in for example org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler. You could choose to handle as many of those that you encounter. Anything that you have not handled and thereby mapped appropriately to a status code other than 500 is a candidate for internal server error. That's why I chose Throwable for 500. Point is no one can predict what exception will be encountered in a method. Any unchecked exceptions is possible maybe due to bad code or maybe database down or network. As long as the framework exceptions are handled specifically everything else is a candidate for 500. But its really upto you how you design it.

Hi Simon,

I personally think that should change eventually. But not immediately.

I do understand from the springdoc openapi folks that they already support @QueryDslPredicate, spring-hateoas and Pageable ..

There is still more work to support: @RepositoryRestResource and the other spring-data-rest. Right now focus is on the core functionalities.

Raghu

You are right. That is sample GlobalControllerAdvice is given as what you can use for a starting point. You should add more specific method handlers based on what you encounter. You might also want to Create your own Problem and ErrorMessage classes with more details

I almost missed your message.

Try calling this from suitable placein the code

SpringDocUtils.getConfig().addResponseWrapperToIgnore(Problem.class);

SpringDocUtils.getConfig().addResponseWrapperToIgnore(ErrorMessage.class);

But personally I prefer including such classes and conveying clearly what is expected

Thanks for the kind words. I am just trying to learn myself and help as much as I could

You can use this -https://github.com/teq-niq/sample/tree/springdoc-openapi-doingmore

branch name- springdoc-openapi-doingmore

git clone url-https://github.com/teq-niq/sample.git

Follow the Readme

I will tomorrow have it mentioned inside the article. Dont want to disturb the Editors on a Sunday.

Don't know why the line numbers are interfering. Will check with the editors.

Meanwhile I have Noted what you said. will do it. Give me some time.

Will update a git repository url for sample code. Thanks.

You mean for my sample code-Currently haven't provided it. Will do that after some time. However if you copy paste carefully it should work.

Great. Hope you like it.

I am unable to see the image. If you describe the problem it might help.

Also dont forget to go through part II- https://dzone.com/articles/doing-more-with-springdoc-openapi . There will be a part III also

Pls clone from here -- https://github.com/springdoc/springdoc-openapi.git

Once again thanks for pointing it out. You can also use the issue tracker for suggesting any improvements.

Yes. Lots of fixes, improvements are in pipeline and include the bug you pointed out. As I said earlier do feel free to clone from master branch (where your bug is fixed already )while we wait eagerly for the next release.

When I say it will be out in next release it basically means that the change has been done and is there in the master branch which usually is a snapshot. When a release happens it will be available through maven central. You can always clone from git and use the fix if in a hurry.

Shalini, Thats a very good catch. It will be out in next release.

Thanks for pointing it out

Hi,

1. I am using the dependencies as shown in https://spring.io/guides/gs/rest-service/ and https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api.

2. About @ApiModelProperty noted will make @ApiXX available soon. It was in my pipeline. (Update: Its been available in last few versions of the maven jar. Also note: Some attributes of the various @ApiXX are ignored by springfox and simplified-spring-swagger because they can be supreflous and not needed)

Meanwhile I hope you liked the part where I show how to automatically leverage the validation constraints and show in the swagger documentation and swagger ui.

Do please visit https://bitbucket.org/tek-nik/simplified-swagger-examples/src/master/ and try out the examples.

Hope you find some of it useful.

Thanks.

Raghu