java OpenAPI java openapitools

一、Open API简介

Open API规范(Open API Specification)以前叫做Swagger规范，是Rest API的API描述格式，
Open API文件允许描述整个API,包括：

• 每个访问地址的类型，POST 或GET
• 每个操作的参数，包括输入和输出参数
• 认证方法（加密，认证信息）
• 连接信息，声明，使用团队和其它信息
  Open API规范（OAS）为REST API定义了一个与语言无关的标准接口，可以使用YAML或JSON格式进行编写，这样更有利于我们和机器阅读，允许人和计算机发现和理解服务的功能，而无需访问源代码，文档或通过网络流量检查。正确定义后，消费者可以使用最少量的实现逻辑来理解远程服务并与之交互

二、Swagger简介

Swagger是一套围绕Open API规范构建的开源工具，可以帮助设计，构建，记录和使用REST API.
使用Swagger就是把相关的信息存储在它定义的描述文件里面（yml 或json格式），在通过维护这个描述文件可以去更新接口文档以及生成各端代码

三、Springfox简介

使用Swagger如果碰到版本更新或迭代时，只需要更改Swagger的描述文件即可，但是频繁的更新项目版本时很多开发人员认为即使更新描述文件（yml或json）也是一种工作负担，直接去修改代码，不去修改描述文件，这样基于描述文件生成接口文档失去意义。
Spring-fox根据代码生成接口文档，所以正常版本迭代时，修改代码即可，不需要修改描述文件
它利用自身AOP特性，把Swagger集成进来，底层还是Swagger，但是使用起来方便很多

四、Swagger入门案例

准备工作： idea创建springboot项目
pom.xml文件加依赖

<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>

主启动类加注解@EnableSwagger2

浏览器访问 http://localhost:8080/swagger-ui.html 出现如下界面

原生的swagger2提供接口UI界面不是很优雅，然而swagger-bootstrap-ui为swagger2改善了优雅展示

pom文件添加依赖

<!-- 优化界面UI -->
       <dependency>
       <groupId>com.github.xiaoymin</groupId>
       <artifactId>swagger-bootstrap-ui</artifactId>
       <version>1.9.6</version>
       </dependency>

SwaggerConfig 类配置

/**
 * 配置文档内容
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * @return Docket 摘要对象，通过对象配置描述文件的信息
     */
    @Bean //创建了Docket类型的对象，并使用spring容器管理，Docket是swagger的全局对象
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)//swagger2
                .apiInfo(apiInfo())//给Docket上下文配置api描述信息
                .groupName("zhanlijuan")
                .select()//获取Docket中的选择器，返回ApiSelectorBuilder，构建选择器的，如：扫描哪个包的注解
                .apis(RequestHandlerSelectors.basePackage("com.cy.jt.security.controller"))//设定扫描哪个包（包含子包）的注解
                .paths(PathSelectors.any())
                .build();//重新构建Docket对象
    }

    //API帮助文档的描述信息 information
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()//创建一个构建器
                .title("Swagger框架学习帮助文档")
                .description("犹抱琵琶半遮面")
                //服务条款网址
                .termsOfServiceUrl("http://zhanlijuan.cn/")
                .version("1.0")
                //配置swagger文档的主体内容 文档发布者名称 文档发布者网站地址 文档发布者电子邮箱
                .contact(new Contact("詹莉娟", "http://zhanlijuan.cn/", "[e-mail]"))
                .build();//构建一个对象
    }
}

五、自定义注解配置

自定义注解设置不需要生成接口文档的方法
自定义注解

/**
 * @interface代表当前类是个注解
 * @Target描述当前注解可以定义在什么资源上
 * @Retention 当前注解在什么时候有效，属性value定义具体的生效的标记，RUNTIME运行时有效，SOURCE源码中有效，CLASS字节码中有效
 */
@Target({ElementType.METHOD,ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface MySwaggerAnnotation {
    //自定义注解中的属性，相当于@MySwaggerAnnotation(value="")
    String value() default "";
}

配置类配置

.apis(
                        Predicates.not(//取反 false-->true true-->
                                RequestHandlerSelectors.withMethodAnnotation(//当方法有MySwaggerAnnotation注解的时候返回true
                                        MySwaggerAnnotation.class)//方法上有什么注解的时候返回true,
                        )
                )

不需要生成接口文档的方法上添加自定义注解

六、路径范围配置

.paths(
                        //使用正则表达式，约束生成API文档的路径地址"."代表任意字符，“*”代表0-n个任意字符 相当于/doDelete/**
                        Predicates.or(//多个规则符合任意一个即可
                                PathSelectors.regex("/.*"),
                                PathSelectors.regex("/swagger2/.*")
                        )
                )

七、Swagger2常用注解

1 @Api

@Api是类上的注解，控制整个类生成接口信息的内容

tags:给当前类型定义别名，可以有多个，定义几个别名，在ui视图中就显示几个控制器访问菜单

description：描述，已经过时

2 @ApiOperation

类或方法上定义，value给当前信息提供的一个描述，必须提供

3 @ApiParam

描述参数

@ApiOperation(value = "post，执行数据查询操作",notes="Swagger学习使用-处理post请求的方法")
    @PostMapping("/post")
    public String post(@ApiParam(name = "用户名(username)",value = "新增用户时提供的用户名",required = true) String username, @ApiParam(name = "密码(password)",value = "新增用户时提供的密码",required = true)String password){
        return "post";
    }

4 @ApiIgnore

忽略当前注解描述的方法或类型不生成帮助文档，和上面自定义注解一样的效果，自定义注解可以完全不用，只用@ApiIgnore一样的效果

@ApiIgnore
    @GetMapping("/get")
    public String get(String a,String b){
        return "get";
    }

5 @ApiImplicitParam[s]

方法上描述方法的参数

@ApiImplicitParam 定义唯一一个方法参数描述

@ApiImplicitParams 定义方法上的多个参数

效果等同于@ApiParam注解，只是一个用在参数上面，一个用在方法上

6 @ApiModel

描述一个实体类型，这个实体类型如果成为任何一个生成api帮助文档方法的返回值类型时，此注解被解析
描述实体的属性 ApiModelProperty

@Data
@ApiModel(value = "自定义实体MyEntity",description = "MyEntity存储用户数据")
public class MyEntity {

    @ApiModelProperty(value = "主键",name = "主键(id)",required = false,example = "1",hidden = false)
    private Integer id;
    @ApiModelProperty(value = "姓名",name = "姓名(name)",required = false,example = "张三",hidden = false)
    private String username;
    private String password;
}

@GetMapping("/getMyEntity")
    public MyEntity getMyEntity(){
        return new MyEntity();
    }