Security is not added to Swagger from Open API generator - spring-boot

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

Related

Adding base path to swagger documentaion

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.

How to integrate Zuul with Swagger

I faced with some issue generating swagger documentaion in my microservices project. When I add zuul custom routings swagger documentation becames inconsistent.
Examples:
RestController:
#RestController
public class Controller {
#PostMapping("/foo")
public void foo() {}
}
Zuul routings:
zuul:
routes:
foo:
path: /bar/**
url: http://localhost:8080/foo
Swagger configuration
#Configuration
#EnableSwagger2
public class SwaggerConfig {
#Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("my.package"))
.build();
}
}
What I need: Swagger UI displays /bar endpoint
What I get: Swagger UI displays /foo endpoint (and it's useless for frontend developers because they generates their components in runtime using swagger)
So, is there any solution how can I configure swagger or zuul to avoid the problem?
We had to add zuul configuration in application.yml file.
# custom configuration - used by swagger to rename endpoints in documentation
springfox:
documentation:
swagger:
v2:
path: /api/uaa/api-docs
whitelistInternal:
- method: GET
path: '/api/**/api-docs'
- method: GET
path: '/swagger-ui.html'
- method: GET
path: '/swagger-resources/**'
Please, check lines that suit you.
This is an example how it can be done
https://dzone.com/articles/centralized-documentation-in-microservice-spring-b

Spring Boot + Swagger-Ui yml generate

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.

Hide Feign client endpoints in Swagger

I am using Springboot autoconfiguration, and currently all my Feign endpoints are exposed in swagger-ui. How can I disable this feature?
You can set this in your application.properties as:
endpoints.enabled=false
endpoints.health.enabled=true
endpoints.loggers.enabled=true
In your case it will be something like
endpoints.feign.***=true
But this is not disabling for swagger but endpoints exposure themselves. For Swagger you have to markup them explicitly with #Api#hidden() for example.
So far the best way to not include unrelated endpoints is through Swagger Docker, e.g.
#Configuration
#EnableSwagger2
class SwaggerConf {
#Bean
Docket allApis() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("all")
.select().apis(RequestHandlerSelectors.basePackage("com.example.base"))
.build();
}
}
Simplest solution that worked for me is to add #ApiIgnore to the Feign Client
#ApiIgnore
#FeignClient()
public interface FeignApi {
}

Adding authorization to Annotation-driven swagger.json with Jersey 2 and Spring Boot

I'm trying to add Basic Authentication to Swagger UI for a to a Swagger-annotated Jersey 2.0 web service built with Spring Boot. I'm using:
Spring Boot 1.5.4
spring-boot-starter-jersey
Swagger UI 3.0.4
(Maven package) swagger-jersey2-jaxrs 1.5.13
I'm able to generate a swagger.json file with the following JerseyConfig and with Swagger annotations on my Resources. This article was immensely helpful in getting this far.
#Component
public class JerseyConfiguration extends ResourceConfig {
private static Log logger = LogFactory.getLog(JerseyConfiguration.class);
#Value("${spring.jersey.application-path:/}")
private String apiPath;
public JerseyConfiguration() {
registerEndpoints();
configureSwagger();
}
private void registerEndpoints() {
register(MyEndpoints.class);
// Generate Jersey WADL at /<Jersey's servlet path>/application.wadl
register(WadlResource.class);
// Lets us get to static content like swagger
property(ServletProperties.FILTER_STATIC_CONTENT_REGEX, "((/swagger/.*)|(.*\\.html))");
}
/**
* Configure the Swagger documentation for this API.
*/
private void configureSwagger() {
// Creates file at localhost:port/swagger.json
this.register(ApiListingResource.class);
this.register(SwaggerSerializers.class);
BeanConfig config = new BeanConfig();
config.setConfigId("example-jersey-app");
config.setTitle("Spring Boot + Jersey + Swagger");
config.setVersion("2");
config.setContact("Me <me#example.com>");
config.setSchemes(new String[] {"http", "https"});
config.setResourcePackage("com.example.api");
config.setBasePath(this.apiPath);
config.setPrettyPrint(true);
config.setScan(true);
}
}
Now I want to be able to use Basic Authentication to connect to these services from Swagger UI. I've configured it in Spring and can use it to authenticate to the site, but not from Swagger UI.
Unfortunately, none of the Spring Boot examples currently on the Swagger sample site include Jersey and authentication, and none of the Jersey examples use Spring Boot and #SpringBootApplication like I'm using on in my project.
How do I get Basic Auth to show up in the Swagger UI?
I was able to get this to work by adding ServletConfigAware to JerseyConfiguration. Then I could use the same style of Swagger configuration used in the Swagger Bootstrap.java examples.
#Component
public class JerseyConfiguration extends ResourceConfig implements ServletConfigAware{
private ServletConfig servletConfig;
// ... this is all unchanged ...
/**
* Configure the Swagger documentation for this API.
*/
private void configureSwagger() {
// Creates file at localhost:port/swagger.json
this.register(ApiListingResource.class);
this.register(SwaggerSerializers.class);
BeanConfig config = new BeanConfig();
// ... this is all unchanged ...
config.setScan(true);
Swagger swagger = new Swagger();
swagger.securityDefinition("basicAuth", new BasicAuthDefinition());
new SwaggerContextService().withServletConfig(servletConfig).updateSwagger(swagger);
}
#Override
public void setServletConfig(ServletConfig servletConfig) {
logger.info("Setting ServletConfig");
this.servletConfig = servletConfig;
}
}
After making these changes, and adding annotations like the following to my endpoints:
#Api(value = "/api", description = "My super API",
authorizations = {#Authorization(value="basicAuth")})
#Path("api")
#Component
public class MyApi {
I saw the following changes:
Added to my swagger.json:
"securityDefinitions":{"basicAuth":{"type":"basic"}}
...
"security":[{"basicAuth":[]}]}}
Also, in Swagger UI, a new green button appeared in the same row as the Schemes dropdown, that says "Authorize" with an open lock on it. If I click on it, a popup shows up where I can enter the username and password. Now those credentials are sent to the API when I use the Swagger UI "Try It" feature.

Resources