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)
Related
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.
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)
We are in a process of implementing Swagger for our REST APIs in a Spring Boot Application. Along with adding YAML files, we have also made changes to Spring Boot configurations to include a reg-ex pattern.
#Bean("myApi")
public Docket myApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(myApiPaths())
.build()
.pathMapping("/");
}
private Predicate<String> myApiPaths() {
return PathSelectors.regex("/v1/my/path/.*");
}
Currently all such YAML files are included in one library and are always available for all spring boot components. Because of this swagger-ui shows up all end points defined. This is why we were relying on path selectors so that only those matching patterns will be exposed.
But above code does not seem to be working. Despite trying different regex patterns, RequestHandlers I am still seeing the APIs which are not implemented on given Spring Boot Component.
Any help here will be appreciated.
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