RESTful API

REST全称是Representational State Transfer，中文意思是表述性状态转移。REST指的是一组架构约束条件和原则。如果一个架构符合REST的约束条件和原则，我们就称它为RESTful架构。

RESTful本质是一种软件架构，也是一种软件设计风格，将网络上的事物抽象为资源，每个资源都有一个资源标识，通过http协议使用URI访问资源。

URI设计技巧:

• 使用_或-来让URI可读性更好
• 使用/来表示资源的层级关系
• 使用?用来过滤资源
• ,或;可以用来表示同级资源的关系

RESTful架构应该遵循统一接口原则，统一接口包含了一组受限的预定义的操作，不论什么样的资源，都是通过使用相同的接口进行资源的访问。接口应该使用标准的HTTP方法如GET，PUT和POST，并遵循这些方法的语义。

GET：从服务器取出资源（一项或多项）。

POST：在服务器新建一个资源。

PUT：在服务器更新资源。

PATCH：在服务器更新资源。

DELETE：从服务器删除资源

Swagger介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger2也提供了强大的页面测试功能来调试每个RESTful API。它主要包含三部分：

• Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。
• Swagger UI:提供了一个可视化的UI页面展示描述文件。可以做一些的接口请求。
• Swagger Editor: 编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

SpringBoot集成Swagger2

在pom中添加Swagger依赖，如下图：

<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>/2添加swagger配置类

添加swagger配置类

/**
 * @Description: swagger 配置类
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 创建API
     */
    @Bean
    public Docket createRestApi() {
        // 指定扫描包路径
        return new Docket(DocumentationType.SWAGGER_2) // 指定生成的文档的类型是Swagger2
//                .pathMapping("/swagger")
                // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）,配置文档页面的基本信息内容
                .apiInfo(apiInfo())
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 扫描所有有注解的api，用这种方式更灵活
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                // 扫描所有 .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any()).build();
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo() {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                // 设置标题
                .title("描述：Spring Boot中使用Swagger2构建RESTful APIs")
                // 描述
                .description("swagger 测试demo")
                //作者信息、联系方式：Contact(String name, String url, String email)
                .contact(new Contact("dgy","https://baijiahao.baidu.com/u?app_id=1711846764618900","dobester@163.com"))
                // 版本
                .version("版本号: 1.0.1")
                .build();
    }
}/3在controller中添加注解,

在controller中添加注解,

注解解释：

• @Api 修饰整个类，描述Controller的作用。
• @ApiOperation 修饰一个类的一个方法，或者说一个接口 ，可以描述这个方法的功能和注意事项。若不使用则用函数名作为方法功能。参数：value="说明方法的用途、作用"，notes="方法的备注说明"
• @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面。name：参数名，value：参数的汉字说明、解释，required：参数是否必须传，paramType：参数放在哪个地方（header --> 请求参数的获取：@RequestHeader，query --> 请求参数的获取：@RequestParam，path（用于restful接口）--> 请求参数的获取：@PathVariable，body（不常用），form（不常用）)，dataType：参数类型，默认String，其它值dataType="Integer"，defaultValue：参数的默认值
• @apiResponses：用在请求的方法上，表示一组响应
• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息。
• @ApiImplicitParams 修饰方法，可以描述这个方法的参数的作用。若不使用则用参数名作为参数的作用。
• @ApiModel 修饰实体类，可以描述这个类的功能。
• @ApiModelProperty 修饰实体类的属性，可以描述这个属性的作用。
• @ApiIgnore修饰参数、方法和类，可以在自动生成文档时对修饰的对象进行忽略。
• @ApiError ：发生错误返回的信息

在浏览器输入localhost:8080/项目名/swagger-ui.html，查看接口信息，如下图：

点击控制器controller，展示控制器下的接口，如下图所示：

点击控制器下的接口，可以查看接口详细信息，如下图：

点击“Try it out”-->输入参数--->点击“Execute”，可以测试接口，如下图所示：

可以看到返回信息code是200，Response body是hello,dgy。

总结：如果感觉Swagger并没有实际上那么方便，还可以集成Knife4j进行接口调试。knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,具有小巧,轻量,并且功能强悍的优点。knife4j的集成和swagger的集成类似，这里就不再赘述了。