swagger2

swagger2

导包

<!-- swagger -->
<swagger.version>2.7.0</swagger.version>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>${swagger.version}</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>${swagger.version}</version>
</dependency>

启动类加载

@SpringBootApplication
@EnableSwagger2
public class LoginApplication {
    public static void main(String[] args) {
        SpringApplication.run(LoginApplication.class, args);
    }
}

config

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 是否开启（生成环境隐藏）
                .enable(true)
                .select()
            	// 扫描controller包里面的所有注解
                .apis(RequestHandlerSelectors.basePackage("com.tenero.login.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("构建swagger")
                .description("swagger测试项目")
                .termsOfServiceUrl("更新代码的网址")
                .contact("程序猿")
                .version("1.0")
                .build();
    }


}

注解

注解	解释	参数
@Api	修饰整个类，描述Controller的作用	tags=“说明该类的作用，可以在UI界面上看到的注解” value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”
@ApiOperation	描述一个类的一个方法，或者说一个接口	value=“说明方法的作用 ”notes=“方法的备注说明”
@ApiModelProperty	用在属性上，描述响应类的属性	value=“说明方法的作用 ”required=“是否必须(true/false)”
@RequestBody	当请求数据描述时	value=“说明方法的作用 ”required=“是否必须(true/false)”

注意点

当配置安全登录框架时，需要对swagger-ui的路径放行，即免登录即可访问

shiro

    /**
     * 拦截器
     * @param defaultWebSecurityManager
     * @return
     */
    @Bean
    public ShiroFilterFactoryBean shiroFilterFactoryBean(@Qualifier("securityManager") DefaultWebSecurityManager defaultWebSecurityManager){
        ShiroFilterFactoryBean shiroFilterFactoryBean = new ShiroFilterFactoryBean();

        shiroFilterFactoryBean.setSecurityManager(defaultWebSecurityManager);

        /**
         * 配置角资源过滤器
         */
        LinkedHashMap<String, String> stringStringLinkedHashMap = new LinkedHashMap<>();
        // 对以下路径放行
        stringStringLinkedHashMap.put("/swagger-ui.html","anon");
        stringStringLinkedHashMap.put("/swagger-resources/**", "anon");
        stringStringLinkedHashMap.put("/webjars/**", "anon");
        stringStringLinkedHashMap.put("/v2/**", "anon");
        stringStringLinkedHashMap.put("/swagger-resources/configuration/security","anon");
        stringStringLinkedHashMap.put("/swagger-resources/configuration/ui","anon");

        shiroFilterFactoryBean.setFilterChainDefinitionMap(stringStringLinkedHashMap);

        return shiroFilterFactoryBean;
    }

Spring Security

/**
* 在 Security 的配置类中重写 configure 方法添加白名单即可：
*/
@Override
public void configure ( WebSecurity web) throws Exception {
    web.ignoring()
      .antMatchers("/swagger-ui.html")
      .antMatchers("/v2/**")
      .antMatchers("/swagger-resources/**");
} 

如果在properties文件或yml文件中添加了如下配置，访问swagger-ui界面时，需在路径上加 /shiro 如：

http://localhost:8088/shiro/swagger-ui.html

如果出现如下错误，springboot版本太高，修改为2.5版本即可，还有一种可能就是你的mapping注解路径写重复了

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

如果启动类加了@ComponentScan注解，那么将扫描不到controller包，ui界面将没有接口展示