Swagger-UI与Spring Cloud整合与安全设置

2019独角兽企业重金招聘Python工程师标准>>>

swagger ui是一个API在线文档生成和测试的利器，在某种程度上可以媲美常用的postman，网上有很多它的整合教程，但是没有考虑到安全问题，下面是它的整合流程。

1、maven依赖：

    <!-- Swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>

 

2、启动主类添加注解

@EnableWebMvc

 

3、创建Swagger2类放在与启动主类同一目录下

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;

import com.google.common.base.Predicates;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * 
 * @Title: Swagger设置类
 * @Package com.lovnx.charge 
 * @author yezhiyuan   
 * @date 2017年5月10日 上午9:45:55 
 * @version V1.0
 */
@Configuration  
@ComponentScan(basePackages = { "com.lovnx.*.controller.*" })//配置controller路径
@EnableSwagger2
@SuppressWarnings({"unchecked","deprecation"})
public class Swagger2 {  

    @Bean  
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)  
                .apiInfo(apiInfo())  
                .select()
                .paths(Predicates.or(
                //这里添加你需要展示的接口
                        PathSelectors.ant("/account/**"),
                        PathSelectors.ant("/xxx/**"),
                        PathSelectors.ant("/qqq/**"),
                        PathSelectors.ant("/eee/**")
                                    )
                        )
                .build();  
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()  
                .title("API平台名字")
                .description("说明RESTful APIs")
                .contact("xxx@qq.com") 
                .version("1.0")
                .build();  
    }
}  

 

4、Swagger配置路径重定向（不加这个类会报错）

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

/**
 * 
 * @Title: Swagger配置路径重定向
 * @Package com.config 
 * @author yezhiyuan   
 * @date 2017年5月10日 上午9:45:16 
 * @version V1.0
 */
@Configuration
public class SwaggerWebMvcConfig extends WebMvcConfigurerAdapter {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

 

5、添加注解

·常规添加

类上添加：@Api(description="这个controller是干嘛的")
方法上添加：@ApiOperation(value="这个方法是干嘛的", notes="详细注释")

·参数上添加

@RequestMapping(value = "/add", method = RequestMethod.POST)
@ApiOperation(value = "添加用户", notes = "增加用户")
public Result<UserVo> add(
  @ApiParam(name = "token", value = "token",required = true) 
  @RequestParam(name = "token", required = true) 
  String token,
  @ApiParam(name = "userName",value = "用户昵称",required = true)
  @RequestParam(name =  "userName",required = true)
  String userName,
  @ApiParam(name = "mobile",value = "手机",required = true)
  @RequestParam(name = "mobile",required = true)
  String mobile) {

·展开bean对象参数

    public Ret<FileSimpleListRetDTO> simpleList(@Validated @ModelAttribute FileSimpleListDTO fileSimpleQueryDTO) {//..}

·忽略bean自定义参数说明显示

@ApiOperation(value = "更新员工信息", notes = "更新员工信息", response = SwaggerSimpleResultConstant.class)
@ApiImplicitParams({
    @ApiImplicitParam(name = "id", value = "主键ID", required = true, paramType = "path"),
    @ApiImplicitParam(name = "name", value = "姓名", required = true, paramType = "query")})
@RequestMapping(value = "/{id}", method = { RequestMethod.PUT })
public Map<ControllerResultConstant, Object> edit(@ApiIgnore Employee employee) {

·直接在bean中添加参数说明

@ApiModel(value = "用户信息") 
public class UserVo { 
  @ApiModelProperty(value = "用户id", required = true)
  private long userId; 
  @ApiModelProperty(value = "昵称", required = true) 
  private long userName; 

说明： 
@ApiModel(value = “用户信息”) 解释实体bean 
@ApiModelProperty(value = “用户id”, required = true) 解释属性

6、配置完成，访问API页面

http://localhost:服务端口/swagger-ui.html

 

7、整合spring Security实现访问API页面输入用户名密码

maven依赖：
<dependency>  
        <groupId>org.springframework.boot</groupId>  
        <artifactId>spring-boot-starter-security</artifactId>  
</dependency>

配置文件添加：
security.basic.path=/swagger-ui.html
security.basic.enabled=true
security.user.name=lovnx
security.user.password=123456

转载于:https://my.oschina.net/u/199525/blog/1524197