Swagger接口文档使用

1.Swagger

• API 自动生成同步的在线文档
• 提供 Web 页面在线测试 API

2.Swagger使用

1.添加依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

2.application.yml配置swagger

#自定义配置
swagger20211010:
  title: 暑假线上班演示RESTful API
  description: 开发人员！
  version: 1.0
  contactName: qcby
  contactEmail:
  contactUrl:
  basePackageRest: com.qcby.shujia.demo.controller 
   #自动扫描的包路径
  termsOfServiceUrl:

2.建立实体类swaggerProperties

@Component
@ConfigurationProperties(prefix = "swagger20211010")  
//要和你配置的名字一样
@Data
public class SwaggerProperties {
    private String title;
    private String contactName;
    private String contactUrl;
    private String contactEmail;
    private String version;
    private String description;
    private String basePackageRest;
    private String termsOfServiceUrl;
}

3.建立配置类SwaggerConfig

@Configuration
@EnableSwagger2// 开启Swagger2/接口文档
public class SwaggerConfig {


    @Autowired
    private SwaggerProperties swaggerProperties;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("REST接口")
                .apiInfo(apiInfo())
                .select()
                //  配置自动扫描那些包下类型生成接口文档
                .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackageRest()))
                .build();
    }
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title(swaggerProperties.getTitle())
                //创建人
                .contact(new Contact(swaggerProperties.getContactName(), swaggerProperties.getContactUrl(),swaggerProperties.getContactEmail()))
                //版本号
                .version(swaggerProperties.getVersion())
                //描述
                .description(swaggerProperties.getDescription())
                .build();
    }
}

4.需要在WebMvcConfig配置类中设置不拦截

// 标识属于一个配置值类  =>  @Component
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // 吧登录拦截器注册到spring mvc中
        registry.addInterceptor(loginInterceptor())
                // 该拦截器拦截那些路径？  /** 代表所有路径
                .addPathPatterns("/**")
    // 那些路径不拦截=>  以login开头的路径不拦截
                .excludePathPatterns("/login/**","/error/**","/userBlog/**"
                        ,"/csrf/**" ,"/webjars/**" ,"/swagger-ui.html/**","/swagger-resources/**");
    }

    @Bean  //  new一个对象放入到spring容器中  类似于<bean id=""/>  和 @Component实际效果一致
    public LoginInterceptor loginInterceptor(){
        return new LoginInterceptor();
    }
}

3.Swagger注解的使用

//  controller类
@Api(tags = {"通用接口"})


// 方法
@ApiOperation("演示接口")

// 参数
@ApiImplicitParams(
    {@ApiImplicitParam(name = "Authorization", 
        value = "Authorization token", required = true, 
        dataType = "string", paramType = "header")}
        )
        
     /*@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值*/

// 实体类  
@ApiModel("用户实体")       
// 实体类字段
@ApiModelProperty(value = "创建时间")

4.Swagger测试

直接请求swagger-ui.html