Swagger使用手册

Swagger使用手册

@Author: 小小程序员

@date: 2022年12月14日

Swagger3

依赖

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>

主启动类加上：@EnableOpenApi

新建一个配置类

@Configuration

@Slf4j
public class SwaggerConfig extends WebMvcConfigurationSupport {


/**
    * 创建API应用
    * apiInfo() 增加API相关信息
    * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
    * 本例采用指定扫描的包路径来定义指定要建立API的目录。
*
    * @return
*/
@Bean
public Docket createRestApi() {
   log.info("加载swagger配置类......");
   return new Docket(DocumentationType.SWAGGER_2)
           .apiInfo(apiInfo())
           .select()
           .apis(RequestHandlerSelectors.basePackage("com.qyq.controller"))
           .paths(PathSelectors.any())
           .build();
}

/**
    * 创建该API的基本信息（这些基本信息会展现在文档页面中）
    * 访问地址：http://项目实际地址/swagger-ui.html
    * @return
*/
private ApiInfo apiInfo() {
   return new ApiInfoBuilder()
           .title("定时测试")
           .description("用spring提供的定时任务去数据库查询数据，然后更改数据")
           .termsOfServiceUrl("hello.com")
           .contact(new Contact("qyq","hello.com","邮箱地址"))
           .version("1.0")
           .build();
}

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
   registry.
           addResourceHandler("/swagger-ui/**")
           .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/")
           .resourceChain(false);
}

@Override
public void addViewControllers(ViewControllerRegistry registry) {
   registry.addViewController("/swagger-ui/")
           .setViewName("forward:/swagger-ui/index.html");
}

}

Swagger2

（一）Swagger

Swagger是一套围绕Open API规范构建的开源哦工具，可以帮助设计、构建、记录和使用REST API。

Swagger工具包括：

• Editor：基于浏览器编辑器，可以在里面编写Open API规范，类似markdown，具有实时预览描述文件的功能。
• UI：将Open API规范呈现为交互式API文档，用可视化UI展示描述文件。
• Codegen：将OpenAPI规范生成为服务求存根和客户端库，通过Codegen可以将描述文件生成html格式和cwiki形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。
• Inspector：和UI类似，但是可以返回更多信息，也会保存请求的实际参数数据。
• Hub：继承了上面所有功能。

使用Swagger，就是把相关信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。

（二）Springfox

Spring-fox是根据代码生成接口文档，所以正常的进行更新项目版本，修改代码即可，而不需要跟随修改描述文件。Spring-fox利用自身AOP特性，把Swagger集成进来，底层还是Swagger，但是使用起来更加方便。

二、使用

引入依赖

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>2.8.0</version>
</dependency>
<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>2.8.0</version>
</dependency>

主启动类加@EnableSwagger2注解

访问：http://localhost:8080/swagger-ui.html

三、 Swagger配置

@Configuration
public class SwaggerConfig {

    /**
     * Swagger中的全局配置对象
     */
    @Bean
    public Docket docket(){
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        //API帮助文档的描述信息
        ApiInfo apiInfo = new ApiInfoBuilder()
                //配置文档主体内容
                .contact(new Contact("开发者","http://www.baidu.com","xx@163.com"))
                .title("swagger接口开发文档-标题")
                .description("swagger接口开发文档-描述")
                .version("1.1")
                .build();
        docket.apiInfo(apiInfo);
        //获取Docket中的选择器，返回ApiSelectorBuilder。构建选择器，如扫描什么包
        docket.select()
                //扫描规则
                .apis(RequestHandlerSelectors.basePackage("com.qyq.controller"));
        return docket;
    }

}

四、自定义注解

@Target(value = {ElementType.METHOD,ElementType.TYPE} )
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface UnDisplaySwagger {
    String value() default "";
}

//获取Docket中的选择器，返回ApiSelectorBuilder。
        docket = docket.select()
                //扫描规则
                //使用正则表达式，约束生成API文档的路径
                .paths(
                        Predicates.or(
                                PathSelectors.regex("/swagger/.*"),
                                PathSelectors.regex("/demo/.*")
                        )
                )
                .apis(
                        Predicates.and(
                                //取反，true-->false   false-->true
                                Predicates.not(
                                        //当方法上有@UnDisplaySwagger注解的时候，返回ture
                                        RequestHandlerSelectors.withMethodAnnotation(UnDisplaySwagger.class)),
                                Predicates.not(RequestHandlerSelectors.withClassAnnotation(UnDisplaySwagger.class)),
                                //构建选择器，如扫描什么包
                                RequestHandlerSelectors.basePackage("com.qyq.controller")
                        )
                ).build();

注意这里的规则会覆盖，所以要注意规则的前后顺序。比如说这里，如果apis在前，paths在后，则apis的@UnDisplaySwagger注解就会失效。

四、Swagger常用注解

类级别
@Api(tages="显示别名")

方法级别
@ApiOperation(value = "获取方法‘getMethod’",notes = "详细介绍")

public String postMethod(@ApiParam(name = "用户名admin",value = "描述",required = true) @RequestParam String admin,
                @ApiParam(name = "密码password",value = "描述",required = true) @RequestParam String[] password){}

@ApiIgnore //不生成api文档

@ApiModel(...)  //描述一个实体类型，这个实体类型如果成为任何一个生成api帮助文档的方法返回值类型的之后，这个注解被解析。
@ApiModelProperty(...)