# apiversion

**Repository Path**: dadaoziran/apiversion

## Basic Information

- **Project Name**: apiversion
- **Description**: RESTful api 版本注解
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2022-06-06
- **Last Updated**: 2022-06-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RESTful API 版本控制

所有符合 RESTful 风格的API都**必须**提供一个版本号，如果 API 引入了重大更改（例如删除或重命名字 段），则该 API 必须增加其 API 版本号，以确保现有用户代码不会突然中断。
所有的 API 必须保持向后兼容，必须 在引入新版本 API 的同时确保旧版本 API 仍然 可用。
例如，API 可以 使用 v1或v1.0表示版本号，但不建议使用1.0.1表示版本号，更多的分 支的版本号可能会给用户造成困扰。
目前比较常见的两种版本号形式：
1. 通过媒体类型来指定版本信息
```
Accept: application/vnd.example.com.v1+json
```
其中 vnd 表示 Standards Tree 标准树类型，有三个不同的树: x，prs 和 vnd。你 使用的标准树需要取决于你开发的项目。
未注册的树（x）主要表示本地和私有环境 私有树（prs）主要表示没有商业发布的项目 供应商树（vnd）主要表示公开发布的项目
后面几个参数依次为应用名称（一般为应用域名）、版本号、期望的返回格式。
**推荐使用这种方式定制版本号。**

2. 在 URL 中嵌入版本号 
```
https://api.example.com/v1/* https://api.example.com/v2.1/*
```
这种做法的优点是版本号直观、易于调试。

**本程序实现了第1种方式指定 API 版本**

# 使用方法
1. 在pom.xml中引入jar包
```
        <dependency>
            <groupId>cn.myplus.apiversion</groupId>
            <artifactId>apiversion</artifactId>
            <version>1.0-SNAPSHOT</version>
        </dependency>
```
2. 在SpringApplication类加入注解  @EnableApiVersion , 代码如下：
```java
@SpringBootApplication
@Configuration
@EnableApiVersion
public class BlogApplication extends SpringBootServletInitializer {
    public static void main(String[] args) {
        SpringApplication.run(BlogApplication.class, args);
    }

    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
        return application.sources(BlogApplication.class);
    }
}
```
3. 在需要控制版本的Controller的方法或类中加入注解，默认版本都是"v1.0",不需要单独配置。
```java
    @ApiVersion(ApiVersion.V2)
    @GetMapping("/{catalog_id}")
    public ResponseEntity getCatalogV2(@PathVariable("catalog_id") String catalogId) {
        CatalogDto dto = new CatalogDto();
        dto.setId(catalogId);
        dto.setLink(PATH + "/" + catalogId);
        dto.setName("单个目录V2");
        return ResponseEntityUtil.ok(dto);
    }
```