30-Swagger2笔记

一、什么是Swagger?

1、是一款让你更好的书写API文档规范且完整的框架。

2、提供描述、生产、消费和可视化RESTful Web Service。

3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。

二、常用注解

@Api注解可以用来标记当前Controller的功能。
	tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"

@ApiOperation注解用来标记一个方法的作用。
	value="说明方法的用途、作用"
    notes="方法的备注说明"
    
@ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值
	name：参数名
	value：参数的汉字说明、解释
    required：参数是否必须传
    
@ApiImplicitParams({
            @ApiImplicitParam(name = "pageNum",value = "当前页"),
            @ApiImplicitParam(name = "pageSize",value = "页大小"),
    })  
    
@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    	@ApiModelProperty：用在属性上，描述响应类的属性

三、Spring Boot 中使用Swagger

结合swagger-ui-bootstrap 美化、JWT 、 Shiro 认证一起使用

1.导入依赖

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<!--swagger-ui 美化-->
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>swagger-bootstrap-ui</artifactId>
  <version>1.9.6</version>
</dependency>

2.编写Swagger2 Config配置文件

/**
 * Swagger2 配置类
 **/
@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
            	//指定扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.coderman.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(apiInfo())
            	//如果使用了JWT+Shiro 就加上密钥认证
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("素材管理系统-前后端api接口文档")
                .description("swagger-bootstrap-ui")
                .termsOfServiceUrl("http://localhost:8989/")
                .version("1.0")
                .build();
    }
//------------------------如果使用了JWT+Shiro 就加上密钥认证方法----------------------------
    private List<ApiKey> securitySchemes() {
        ArrayList<ApiKey> apiKeyList = Lists.newArrayList();
        apiKeyList.add(new ApiKey("JSON WEB TOKEN(秘钥)", "Authorization", "header"));
        return apiKeyList;
    }

    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts=new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("^(?!auth).*$"))
                        .build());
        return securityContexts;
    }

    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences=new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }
}

3. ShiroConfig 中的配置

@Configuration
public class ShiroConfig {

    @Bean("shiroFilter")
    public ShiroFilterFactoryBean factory(DefaultWebSecurityManager securityManager) {
        ShiroFilterFactoryBean factoryBean = new ShiroFilterFactoryBean();
        factoryBean.setSecurityManager(securityManager);

        // 添加自己的过滤器并且取名为jwt
        Map<String, Filter> filterMap = new HashMap<>();
        filterMap.put("jwt", new JWTFilter());
        factoryBean.setFilters(filterMap);

        //开放API文档接口
        filterRuleMap.put("/swagger-ui.html", "anon");
        filterRuleMap.put("/doc.html", "anon");
        filterRuleMap.put("/webjars/**","anon");
        filterRuleMap.put("/swagger-resources/**","anon");
        filterRuleMap.put("/v2/**","anon");
        factoryBean.setFilterChainDefinitionMap(filterRuleMap);
        return factoryBean;
    }

4.UserController类

@RestController
@RequestMapping("/system/user")
@Api(tags = "系统模块-用户相关接口")
public class UserController {

    /**
     * 用户登入
     */
    @ApiOperation(value = "用户登入", notes = "接收参数用户名和密码,登入成功后,返回JWTToken")
    @PostMapping("/login")
    public String login(
        @RequestBody UserLoginDTO userLoginDTO, 
        HttpServletRequest request) throws SystemException { 
        return "token";
    }
}

5.UserLoginDTO 类

/**
 * 用户登入表单实体
 **/
@Data
@ApiModel(value = "用户登入表单")
public class UserLoginDTO {

    @ApiModelProperty(value = "用户名")
    private String username;

    @ApiModelProperty(value = "密码")
    private String password;
}

6.启动项目

访问： http://localhost:8080/doc.html 到swagger-ui美化界面

访问： http://localhost:8080/swagger-ui.html 到swagger-ui原始界面

7.界面截图