转-（二期）7、swagger2与postman

（二期）7、swagger2与postman

0.3MB

31.3KB

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染变成了：前端渲染、先后端分离的形态，而前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要。包括app开发人员和后端直接的交流都是基于api文档。

手写接口文档

手写Api文档的几个痛点：

文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。

接口返回结果不明确

不能直接在线测试接口，通常需要使用工具，比如postman

接口文档太多，不好管理

swagger就是一款让你更好的书写API文档的框架。

什么是swagger2

编写和维护接口文档是每个程序员的职责，根据Swagger2可以快速帮助我们编写最新的API接口文档，再也不用担心开会前仍忙于整理各种资料了，间接提升了团队开发的沟通效率。

常用注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiParam：单个参数描述

@ApiModel：用对象来接收参数

@ApiProperty：用对象接收参数时，描述对象的一个字段

@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：用在属性上，描述响应类的属性

springboot整合swagger2

第一步：导入pom

<!-- Swagger -->

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger-ui</artifactId>

    <version>2.8.0</version>

</dependency>

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger2</artifactId>

    <version>2.8.0</version>

</dependency>

<!-- END Swagger -->

第二步、SwaggerConfig.java中配置接口文档基本信息和启动swagger2支持

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration

@EnableSwagger2

public class SwaggerConfig {

    @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)

            .apiInfo(apiInfo())

            .select()

            .apis(RequestHandlerSelectors.basePackage("hello"))

            .paths(PathSelectors.any())

            .build();

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()

            .title("Spring Boot中使用Swagger2构建RESTful APIs")

            .description("欢迎来到java思维导图社区学习")

            .termsOfServiceUrl("http://www.java-mindmap.com/")

            .version("1.0")

            .build();

@RequestBody

该注解常用来处理Content-Type: 不是application/x-www-form-urlencoded编码的内容，例如application/json, application/xml等；它是通过使用HandlerAdapter 配置的HttpMessageConverters来解析post data body，然后绑定到相应的bean上的。

restful风格接口

URL定位资源，用HTTP动词（GET,POST,DELETE,DETC）描述操作。

识别(identify)、表示(represent) 、交互(interact with)。

看Url就知道要什么

看http method就知道干什么

看http status code就知道结果如何

1. REST描述的是在网络中client和server的一种交互形式；REST本身不实用，实用的是如何设计 RESTful API（REST风格的网络接口）；

2. Server提供的RESTful API中，URL中只使用名词来指定资源，原则上不使用动词。“资源”是REST架构或者说整个网络处理的核心。比如：

http://api.qc.com/v1/newsfeed: 获取某人的新鲜;

http://api.qc.com/v1/friends: 获取某人的好友列表;

http://api.qc.com/v1/profile: 获取某人的详细信息;

3. 用HTTP协议里的动词来实现资源的添加，修改，删除等操作。即通过HTTP动词来实现资源的状态扭转：

GET 用来获取资源，

POST 用来新建资源（也可以用于更新资源），

PUT 用来更新资源，

DELETE 用来删除资源。比如：

DELETE http://api.qc.com/v1/friends: 删除某人的好友（在http parameter指定好友id）

POST http://api.qc.com/v1/friends: 添加好友

UPDATE http://api.qc.com/v1/profile: 更新个人资料

4. Server和Client之间传递某资源的一个表现形式，比如用JSON，XML传输文本，或者用JPG，WebP传输图片等。当然还可以压缩HTTP传输时的数据（on-wire data compression）。

5. 用 HTTP Status Code传递Server的状态信息。比如最常用的 200 表示成功，500 表示Server内部错误等。

1、REST 是面向资源的，这个概念非常重要，而资源是通过 URI 进行暴露。

比如：左边是错误的设计，而右边是正确的

GET /rest/api/getDogs --> GET /rest/api/dogs 获取所有小狗狗

GET /rest/api/addDogs --> POST /rest/api/dogs 添加一个小狗狗

GET /rest/api/editDogs/:dog_id --> PUT /rest/api/dogs/:dog_id 修改一个小狗狗

GET /rest/api/deleteDogs/:dog_id --> DELETE /rest/api/dogs/:dog_id 删除一个小狗狗

2、REST很好地利用了HTTP本身就有的一些特征，如HTTP动词、HTTP状态码、HTTP报头等等。

HTTP动词

GET     获取一个资源

POST    添加一个资源

PUT     修改一个资源

DELETE  删除一个资源

HTTP状态码

200 OK

400 Bad Request

500 Internal Server Error

HTTP报头

Authorization 认证报头

Cache-Control 缓存报头

Cnotent-Type  消息体类型报头

......

怎么用RESTful

1、每个资源使用2个URL，网址中只能有名词

2、对于资源的操作类型由HTTP动词来表示

3、统一的返回结果

4、返回正确的状态码

5、允许通过HTTP内容协商，建议格式预定义为JSON

6、对可选发杂的参数，使用查询字符串（？）

7、返回有用的错误信息(message)

8、非资源请求用动词，这看起似乎和1中的说法有矛盾，但这里指的是非资源，而不是资源

postman简介

Postman 是一个很强大的 API调试、Http请求的工具，当你还准备拿着记事本傻傻的去写 Form 表单的时候，你来试试 Postman。

Postman 提供功能强大的 Web API 和 HTTP 请求的调试，它能够发送任何类型的HTTP 请求 (GET, POST, PUT, DELETE...)，并且能附带任何数量的参数和 Headers。不仅如此，它还提供测试数据和环境配置数据的导入导出，付费的 Post Cloud 用户还能够创建自己的 Team Library 用来团队协作式的测试，并能够将自己的测试收藏夹和用例数据分享给团队。

postman安装

1、app下载地址