As described in the title - Swagger is not showing API Models and not ignoring default response codes
I have uploaded the source code to - https://bitbucket.org/vambits/inactiveaccounts/src/master/
git clone https://bitbucket.org/vambits/inactiveaccounts.git
I am not sure why the API Model objects: SimpleRequest and SimpleResponse are not showing up in the Swagger UI.
As you can see there are no "Models" at the End.
In the code, i have set .build()).useDefaultResponseMessages(false) but still the default response codes are getting shown. How to fix this??
Note: The functionality of this application is irrelevant.
Swagger Docket Configuration is as below -
#Bean
public Docket swaggerApi()
{
return new Docket(DocumentationType.SWAGGER_2).protocols(Sets.newHashSet("http", "https"))
/*
* Make sure swagger doesn't auto-generate error responses that we won't be using (e.g. 401, 403)
*/
/*
* Since SpringFox doesn't support the #SwaggerDefinition, specify that metadata here
*/
.apiInfo(new ApiInfoBuilder().title("InactiveAccountsApplication Pricing").version("1")
.contact(new Contact("InactiveAccountsApplication Services", null, "abc-services#xyz.com"))
.description(
"InactiveAccountsApplication returns the inactive accounts list")
.build())
.useDefaultResponseMessages(false)
.select()
.apis(RequestHandlerSelectors.basePackage(InactiveAccountsApplication.class.getPackage().getName()))
.paths(PathSelectors.any()).build();
}
I would recommend to use springdoc instead of the springfox libraries, because they are pretty outdated.
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.5.8</version>
</dependency>
Here you can find the documentation including a migration guide
The models should be included out of the box then.
Regarding your second question:
The response codes shown in your screenshot aren't the default response messages. They are the responses that you described in your controller, so I don't understand what the problem is.
Related
Does swagger ui only display models that are used by controllers?
In my spring boot application, I am using swagger 2 to define my api. Few of the models are being used in apis whereas others are not being used directly but I need them in my api doc.
Now when I see the json in swagger editor it displays everything perfectly but swagger ui is only displaying models that are used by controller. Following are my swagger-ui configurations
#Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.search.controller"))
.paths(PathSelectors.any())
.build();
}
It will helpful if anyone could share some feedback on this. Also is there any other tool that could serve this purpose?
Thanks
You could check the generated json or yaml file:
localhost:8080/v2/api-docs
localhost:8080/v2/api-docs.yaml
Edit it to your liking, and use your own documentation source instead.
(This might help with that:
http://editor.swagger.io)
I am currently working on a project where I use spring functional web programming. I usually use annotations of swagger 2 in restController but with functional web programming I can not find where ! The place to tell the app to do a search for endpoints (like basepackage in Docket) and load swagger in an html page.
Here is my code:
#Configuration
public class RouterClient{
#Bean
public RouterFunction<ServerResponse> routes(ClientHandler client){
return route(GET("/api/client"), client::findAll)
.andRoute(POST("/api/client"),client::add);
}
}
Config Class:
#Configuration
public class OpenApiConfiguration{
#Bean
public GroupedOpenApi groupOpenApi() {
String paths[] = {"/api/**"};
String packagesToscan[] = {"com.demo.client"};
return GroupedOpenApi.builder().setGroup("groups").pathsToMatch(paths).packagesToScan(packagesToscan)
.build();
}
}
The dependencies:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-webflux-core</artifactId>
<version>1.2.32</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-webflux-ui</artifactId>
<version>1.2.32</version>
</dependency>
The result :
Functional endpoints are supported since 1.3.8 (early May). See releases on GitHub.
Have a look at this: https://springdoc.org/#spring-webfluxwebmvc-fn-with-functional-endpoints
The easiest way to see your endpoints on the Swagger UI is to add the #RouterOperation annotation to your RouterFunction methods (containing a single route), and specify the beanClass and beanMethod used in it. However, in your case, there are multiple routes on a single method, so you must also use the #RouterOperations annotation. These cases are well documented in the link above.
It seems like the current implementation of springdoc-openapi only allows to manually add the documentation.
set
springdoc.api-docs.enabled=false
This will skip classpath scanning (springfox) for the API annotations. (OAS3 replaced these in v3) and replace them with reading in the spec file (json/yaml).
Put the documentation in the Spec files, as one can generate any number of clients from these. Easiest way to start with legacy code is to copy the /api-docs/ files generated by springfox.
You can go to editor.swagger.io, load in the version 2 yaml and convert it to version 3 if springfox still doesn't do that. Then work with yaml files. (it's a contract UP-Front specification for a reason)
https://springdoc.org/
You need springdoc-openapi-webflux-ui and #RouterOperation.
spring-webflux with Functional Endpoints, will be available in the future release
I am trying to setup swagger for an existing Spring Boot API project. I have discovered that I have two endpoints that cause the http://url/swagger-ui.html file to not render. If I comment out these two endpoints then it does render correctly.
When the two endpoints exist, the http://url/v2/api-docs json file does render successfully. I can take the json from api-docs and paste it into https://editor.swagger.io/ and the html page renders correctly on that site.
The two endpoints that are causing the issue are on root path, and have only a path parameter in the url. They are each in a controller that has #RequestMapping("/") and they are annotated;
#PutMapping(value = "{vaultTitleId}", produces = MediaType.APPLICATION_JSON_VALUE)
#DeleteMapping(value = "{vaultTitleId}")
These two endpoints work correctly, they just are causing some issue with Swagger rendering the HTML. If I remove them, the HTML displays. I have tried moving them into a controller by themselves and seeing if I could prevent swagger from accessing them in the Swagger configuration. But, it seems they only have to exist somewhere where spring boot sees them to prevent the html from displaying.
Any advice is appreciated. I would like to use Swagger, but I am giving up on it for now, and looking at alternative tools.
Gradle
compile("io.springfox:springfox-swagger2:2.9.2")
compile("io.springfox:springfox-swagger-ui:2.9.2")
Swagger Config
#Configuration
#EnableSwagger2
public class SwaggerConfig {
#Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors
.basePackage("com.nextgearcapital.mt.controller"))
.paths(PathSelectors.any())
.build();
}
}
I discovered a work around. This was suggested in another forum.
https://github.com/springfox/springfox/issues/631
The problem is you're endpoints are consuming the endpoint mappings,
you can create a regular expression that resolves it?
#DeleteMapping(value = "{vaultTitleId:^((?!swagger-ui.html).)*$}")
Seems al lil clunky but not sure what the right answer is.
Using a request mapping with a regex to define the path parameter did allow the swagger-ui to display. It is not obvious to me why this works. I would call it more of a work around than an actual solution. But, this is what I am going to be using.
#DeleteMapping(value = "{vaultTitleId:^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$}", produces = MediaType.APPLICATION_JSON_VALUE)
I am working on microservices using spring-boot-1.4.5. We are setting few headers in MDC while the interaction between microservices occurred. These headers are common across the microservices/application.There is an interceptor in each application which will check for this headers if it is not present the call will not reach controller. So for everything works fine. The problem is each application or services exposing a swagger-UI(swagger-ui:2.6.1).
I can able to see swagger-ui and all the endpoints in the application but i don't know how to show the global headers field under each endpoint.
How to customise swagger to show these global headers under each endpoint ?
Any help or hint would be appreciable also i browsed google and saw other posts which are not useful or i couldn't grasp the things properly.
To set global parameters, use ParameterBuilder to build springfox.documentation.service.Parameter and set it to globalOperationParameters.
#Bean
public Docket api() {
Parameter headerParam = new ParameterBuilder().name("TenantId").defaultValue("microservices").parameterType("header")
.modelRef(new ModelRef("string")).description("Tenant Identity").required(true).build();
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.globalOperationParameters(Arrays.asList(headerParam))
.select()
.apis(RequestHandlerSelectors.basePackage("com.app"))
.paths(PathSelectors.any())
.build();
}
In a springboot app context, i'm looking for the .json output of swagger.
Seems that in the docs, the /v2/api-docs is available, but there's nothing within this url in my project.
The UI swagger is available under /swagger-ui.html,
where can I find the json output ?
There is no physical json file/resource. It is generated at run-time and served up from memory.
Secondly the swagger-ui.html and all the javascript/css/images resources are served up from the springfox-swagger-ui library which is packaged up as a web-jars.
Try this one. You will have to provide the group name.
http://<host>:<port>/v2/api-docs?group=<group-name>
You don't have json endpoint out of the box. As I know, you have to build Docket for for every endpoint. Here is an example:
Docket endpointDocket = new Docket(DocumentationType.SWAGGER_2)
.groupName("yourGroupName")
.select()
.paths(regex("yourEndpointUrl"))
.build();
You have to register it in app context. Then you will have url (as mentioned by mephis-slayer):
http://<host>:<port>/v2/api-docs?group=yourGroupName