加上版本号

http://localhost:8080/api/v1/list

一旦api接口确定，不在改变接口实现的业务逻辑

资源路径

URI 不能包含动词，只能是名词。注意的是，形容词也是可以使用的，但是尽量少用。一般来说，不论资源是单个还是多个，API 的名词要以复数进行命名。此外，命名名词的时候，要使用小写、数字及下划线来区分多个单词。这样的设计是为了与 json 对象及属性的命名方案保持一致

【GET】  /v1/tags/{tag_id}

有的时候，当一个资源变化难以使用标准的 RESTful API 来命名，可以考虑使用一些特殊的 actions 命名。

【PUT】  /v1/users/{user_id}/password/actions/modify // 密码修改

请求方式

可以通过 GET、 POST、 PUT、 PATCH、 DELETE 等方式对服务端的资源进行操作。其中：

GET：用于查询资源
POST：用于创建资源
PUT：用于更新服务端的资源的全部信息
PATCH：用于更新服务端的资源的部分信息
DELETE：用于删除服务端的资源。

响应参数

如果是单条数据，则返回一个对象的 JSON 字符串。

{
    "id" : "01234567-89ab-cdef-0123-456789abcdef",
    "name" : "example",
    "created_time": 1496676420000,
    "updated_time": 1496676420000,
    ...
}

如果是列表数据，则返回一个封装的结构体

{
    "count":100,
    "items":[
        {
            "id" : "01234567-89ab-cdef-0123-456789abcdef",
            "name" : "example",
            "created_time": 1496676420000,
            "updated_time": 1496676420000,
            ...
        },
        ...
    ]
}

SpringMVC处理Put或Delete

1、首先在web.xml中配置过滤器

<filter>
        <filter-name>HiddenHttpMethodFilter</filter-name>
        <filter-class>org.springframework.web.filter.HiddenHttpMethodFilter</filter-class>
</filter>
<filter-mapping>
        <filter-name>HiddenHttpMethodFilter</filter-name>
        <url-pattern>/*</url-pattern>
</filter-mapping>

2、form表单配置隐藏域，注意表单中method必须为post，隐藏域中name和value属性如下所示

<form action="/delete" method="post">
    <input name="_method" value="DELETE" type="hidden">
    <input type="submit" value="提交">
</form>

3、处理请求

需要加上@ResponseBody注解，否则报错，加上该注解后，就不能返回视图了

@RequestMapping(value = "/delete",method = RequestMethod.DELETE)
@ResponseBody
public String delete() throws IOException {
        return "delete";
}

Rest 风格 URL

左边是传统的api，右边是Rest风格的api

/get?id=1 ---->/order/1 get

/add ---->/order post

/delete?id=1 --->/order/1 delete

/update?id=1 --->/order/2 put

SpringBoot处理Put或Delete

1、配置 HiddenHttpMethodFilter（不需要了，SpringBoot已经配置好了）

2、form表单配置隐藏域

<form action="/delete" method="post">
    <input name="_method" value="DELETE" type="hidden">
    <input type="submit" value="提交">
</form>

接口开发规范

Api请求及响应规范

为了严格按照接口进行开发，提高效率，对请求及响应格式进行规范化。

1、get 请求时，采用key/value格式请求，SpringMVC可采用基本类型的变量接收，也可以采用对象接收。
2、Post请求时，可以提交form表单数据（application/x-www-form-urlencoded）和Json数据（Content-Type=application/json），文件等多部件类型（multipart/form-data）三种数据格式，SpringMVC接收Json数据使用@RequestBody注解解析请求的json数据。
4、响应结果统一信息为：是否成功、操作代码、提示信息及自定义数据。
5、响应结果统一格式为json。

　　示例

@Data
@ToString
public class QueryResponseResult extends ResponseResult {

    QueryResult queryResult;

    public QueryResponseResult(ResultCode resultCode, QueryResult queryResult) {
        super(resultCode);
        this.queryResult = queryResult;
    }
}

@Data
@ToString
@NoArgsConstructor
public class ResponseResult implements Response {

    //操作是否成功
    boolean success = SUCCESS;

    //操作代码
    int code = SUCCESS_CODE;

    //提示信息
    String message;

    public ResponseResult(ResultCode resultCode){
        this.success = resultCode.success();
        this.code = resultCode.code();
        this.message = resultCode.message();
    }

    public static ResponseResult SUCCESS(){
        return new ResponseResult(CommonCode.SUCCESS);
    }
    public static ResponseResult FAIL(){
        return new ResponseResult(CommonCode.FAIL);
    }
}

public interface Response {
    public static final boolean SUCCESS = true;
    public static final int SUCCESS_CODE = 10000;
}

接口文档的编写

　　Swagger是全球最大的OpenAPl规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。（https://swagger.io/）

　　Swagger常用注解（给前端测试用户提示信息的）

　　在Java类中添加Swagger的注解即可生成Swagger接口，常用Swagger注解如下：

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiModelProperty：用对象接收参数时，描述对象的一个字段 @ApiResponse：HTTP响应其中1个描述 @ApiResponses：HTTP响应整体描述 @ApiIgnore：使用该注解忽略这个API @ApiError ：发生错误返回的信息 @ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

使用

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
 
 
@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"
 
 
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值
 
 
@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类
 
 
@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性

spring boot配置

　　配置

@Configuration
@EnableSwagger2 //注解表示会去com.xuecheng包下找到所有添加了@RestController注解的类，为这个类中的每一个方法生成接口文档
public class Swagger2Configuration {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xuecheng"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("学成网api文档")
                .description("学成网api文档")
//                .termsOfServiceUrl("/")
                .version("1.0")
                .build();
    }
}

　　给接口文档添加注释信息

@Api(value="cms页面管理接口",description = "cms页面管理接口，提供页面的增、删、改、查")
public interface CmsPageControllerApi {
    //页面查询
    @ApiOperation("分页查询页面列表")
    @ApiImplicitParams({@ApiImplicitParam(name="page",value = "页码",required=true,paramType="path",dataType="int"), @ApiImplicitParam(name="size",value = "每页记录数",required=true,paramType="path",dataType="int")})
    public QueryResponseResult findList(int page, int size, QueryPageRequest queryPageRequest);
}

　　测试：启动spring boot，访问：http://localhost:31001/swagger-ui.html，效果如图