I am trying to change the base path of swagger codumentation. Currently I have
#RequestMapping(path = "/api/resourceName/v1")
and swagger config
return new Docket(DocumentationType.SWAGGER_2).
select()
.apis(RequestHandlerSelectors.basePackage("com.company"))
.paths(PathSelectors.ant("/api/**"))
.build()
.apiInfo(apiInfo());
This is giving swagger base path as "basePath": "/"
I want to add base path as "basePath": "/api" so I followed diff threads like this How to change basePath for Springfox Swagger 2.0 and added
return new Docket(DocumentationType.SWAGGER_2).
select()
.apis(RequestHandlerSelectors.basePackage("com.company"))
.paths(PathSelectors.ant("/api/**"))
.build()
.apiInfo(apiInfo())
.pathProvider(new RelativePathProvider(servletContext) {
#Override
public String getApplicationBasePath() {
return "/api";
}
});
now the base path is changed to "basePath": "/api" and I updated my path mapping to #RequestMapping(path = "/resourceName/v1") as base has been added.
When I send the request from swagger, the request is going to /api/resourceName/v1 but the service returns 404.
When I send the request through postman for /resourceName.v1 then it works.
So the api is registred as /resourceName/v1 and the base is just added by swagger on top of it and will not work if the request sent throguh swagger UI
Then I added server.servlet-path=/api to application.properties to register basepath in the request mapping and now swagger shows the base path as /api without needing additional configuration.
But the problem is now swagger documentation is available at http://localhost:8080/api/swagger-ui.html instead of http://localhost:8080/swagger-ui.html. As we have all our other services doc at http://host/swagger-ui.html this is not useful.
Is there any way to add the base and still access the doc at http://host/swagger-ui.html and api's works as expected fro swagger and postman
Yes, you can add base path for all swagger requests. I used following config for this purpose:
#Configuration
#EnableSwagger2
public class SpringFoxConfig {
#Bean
public Docket api() {
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
docket.pathMapping("api");
return docket;
}
}
Hope this helps.
There is way to change the api-doc base path using properties defined in application.properties file.
The properties are:
springfox.documentation.openApi.v3.path=/external/api/app/v3/api-docs
springfox.documentation.swaggerv2.path=/external/api/app/v2/api-docs
This can help you to change the path.
Related
I am working on a new project in my team and we are implementing an API following the API first methodology. We are using openapi-generator-maven-plugin to generate our API from an yml file of format OpenAPI 3.0.3. To generate the swagger file we use springfox 2.9.2. The issue that I am facing is when I am trying to add security to the swagger for the requests.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- bearerAuth: [ ]
The Authorize button doesn't appear in swagger page, only the lock near to the request appears but it doesn't do anything (see picture below).
What I observed is that if I open the /v2/api-docs the swagger json doesn't include the security definitions part.
The only way that I managed to add security is by adding by code in the Docket object the security part like so:
new Docket(DocumentationType.SWAGGER_2)
.securityContexts(Collections.singletonList(securityContext()))
.securitySchemes(Collections.singletonList(bearerJwtKey()))
.select()
.apis(RequestHandlerSelectors.basePackage("com.example"))
.paths(PathSelectors.any())
.build();
Is this the only way to add security to Swagger UI or am I missing something?
Reason: Bearer Auth isn't implemented in spring library yet :(
Workaround solution - extend generated Docket:
Import generated config class and then add a security schema (ApiKey) to the existing Docket bean. Example:
#Configuration
#Import(OpenAPIDocumentationConfig.class) // openapi generated config class
public class SwaggerConfiguration {
#Autowired
ApplicationContext context;
#PostConstruct
public void extendExistingDocketWithSecurity() {
Docket docket = context.getBean(Docket.class);
docker.securitySchemes(Collections.singletonList(bearer()));
}
private static ApiKey bearer() {
// where "bearerAuth" - name of your schema in YML spec. file
return new ApiKey ("bearerAuth", HttpHeaders.AUTHORIZATION, "header");
}
Done! You're awesome!
Now you're using generated swagger config without overriding, but just extending
When configuring a Docket we have to specify the base package where to look for api endpoints. Is it possible to add manually an endpoint which is not mapped to any controller?
I have a legacy application which is a simple Zuul server but it has a swagger-ui, the goal is to specifiy endpoints that are proxied by zuul?
#Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.globalOperationParameters(getHeaders()).select()
.apis(RequestHandlerSelectors.basePackage("package.controllers"))
.additionalApis(Method.PUT, "/my/manual/endpoint") // This does not exist
.paths(PathSelectors.any())
.build();
}
Thanks
Create a swagger-ui with the yaml file generated by swagger-editor
Creating an auto swagger-ui using Annotation was successful.
But I do not know how to create Swagger-ui with yaml created with swagger-editor. Is there anyone who can explain in detail? The development environment uses SpringBoot 2.0.4.
#Configuration
#EnableSwagger2
public class SwaggerConfig {
#Bean
public Docket getApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(paths())
.build();
}
private Predicate<String> paths() {
return Predicates.and(
PathSelectors.regex("/shop.*"),
Predicates.not(PathSelectors.regex("/error.*")));
}
}
The above code can make all the APIs inside the server Swagger-ui.
However, I would like to configure swagger-ui with the yaml file that I wrote myself through the swagger-editor.
I am running a SpringBoot config server (with Vault backend) and tried to add Springfox SwaggerUI to it. But since I do not want a prefix (spring.cloud.config.server.prefix) for my config server, the path mapping between the config server and SwaggerUI results in a conflict.
All my clients ask the config server with the following pattern:
{config-server-host}/{application-name}/{profile}
For example:
{config-server-host}/test-app-one/dev
{config-server-host}/test-app-two/prod
But my SwaggerUI path maps to:
{config-server-host}/swagger-ui.html
As a consequence, the config server complains that the app "swagger-ui" cannot be found or that no profile was specified.
This is the configuration of my Docket bean for the SwaggerUI:
#Configuration
#EnableSwagger2
public class SwaggerConfig {
#Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.paths(not(regex("/error.*")))
.paths(any())
.build()
.pathMapping("/");
}
private ApiInfo apiInfo() {
Contact contact = new Contact({secret}, {secret}, {secret});
return new ApiInfoBuilder().title({secret})
.description({secret})
.version({secret})
.contact({secret})
.build();
}
}
This all results in the following question: I cannot have a prefix for the config server and I want the SwaggerUI url mapped to the standard. Is there any possibility to tell the config server that it should exclude the /swagger* paths?
The spring.cloud.config.server.prefix parameter in the bootstrap.properties file fixed the issue for me.
is it possible to consider the zuul filter (manual or automatic) to show in the swagger?
The issue is the following:
we have a microservice which is the single point of entry for our application and which holds all swagger documentation. in fact it works as a fasade, so it routes the request to the corresponding microservices inside our application. Unfortunately, zuul sometimes it adds something to the route or removes something. therefore the swagger documentation is incorrect, as the base-path is slightly different.
is there any possiblity to influence this?
swagger docket is used with simple lookup:
#Bean
public Docket swaggerSpringfoxDocket() {
this.log.debug("Starting Swagger");
StopWatch watch = new StopWatch();
watch.start();
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.forCodeGeneration(false)
.select()
.paths(regex("/api/.*"))
.build();
watch.stop();
this.log.debug("Started Swagger in {} ms", watch.getTotalTimeMillis());
return docket;
}