Swagger使用简介

最新推荐文章于 2024-01-15 02:29:15 发布

weixin_30608131

最新推荐文章于 2024-01-15 02:29:15 发布

阅读量133

点赞数 1

文章标签：前端后端 java ViewUI

原文链接：http://www.cnblogs.com/companionspace/p/10303064.html

版权

在之前开发时，前端人员总是说：“调好的参数怎么改了？接口不通了，能不能说一下”

我说：“1.文档不够详情，我怎么返回你所想要的数据　　2.我改完接口也告诉你了　　3.这样吧！我以后改接口直接告诉你调式”

后来我看了一篇文章，既可以解决前后端的矛盾，也可以提高工作效率　　　　这就是Swagger

一：swagger是什么？

二：为什么使用swagger？

三：如何搭建一个swagger？

四：在项目中如何集成swagger？

五：是那个用swagger需要注意的问题

六：总结

一：Swagger是什么？

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTfu风格的web服务。目标是使客户端和文件系统作为服务器一同样的速度来更新文件的方法，参数和模型紧密集成到服务器。这个解释简单点来讲就是说，swagger是一款可以根据restful风格生成的接口开发文档，并且支持做测试的一款中间软件。

二：为什么使用swagger？

1.对于后端开发人员来说

不用再手写Wiki接口拼大量参数，避免手写错误
对代码侵入性低，采用全注解的方式，开发简单
方法参数名修改、新增、减少参数都可以直接生效，不用手动维护
缺点：增加了开发成本，写接口还得再写一套参数配置

2.对前端开发来说

后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然
联调方便，如果出了问题，直接测试接口，实时检查参数和返回值，就可以快速定位是前端还是后端的问题

3.对于测试

但对于测试没有前端界面UI的功能，可以直接用它来测试接口
操作简单，不用了解具体代码就可以操作

三：如何搭建一个swagger？

在引入swagger的依赖，目前推荐使用2.7.0版本的，因为2.6.0版本有bug，而其他版本有没有经验验证

　　①引入swagger 依赖库

　　　　<groupId>io.springfox</groupId>

　　　　<artifactId>springfox-swagger2</artifactId>

　　</dependency>

　　　　<groupId>io.springfox</groupId>

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

　　</dependency>

　　②springboot整合swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket productApi(){
        return new Docket(DocumentationType.SWAGGER_2).
                apiInfo(apiInfo()).
                select().
                apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).//添加ApiOpentaion注解的被扫描
                paths(PathSelectors.any()).
                build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder().
                title("swagger和springboot整合").
                description("swagger的api文档").
                version("1.0").build();
    }
}

swagger的注解：
swagger的核心在于注解，接下来就着重说一下swagger的注解

注解名称	注解含义	注解使用地方	注解参数	参数含义
@EnableSwagger2	开启swagger注解	配置类上	无	无
@Api	标识swagger识别的类	Controller类上	value tags description	url的路径值如果设置这个值、value的值会被覆盖对api资源的描述
@ApiIgore	屏蔽显示某个Controller，开启后在swagger上不会显示	COntroller类上	value	值
@ApiOperation	标识swagger识别的方法	Controller类中的方法	value tags description basePath position produces consumes protocols authorizations hidden response responseContainer httpMethod code extensions notes	url的路径值如果设置这个值、value的值会被覆盖对api资源的描述基本路径可以不配置如果配置多个Api 想改变显示顺序位置 For example，"application/json，application/xml" For example，"application/json，application/xml" Possible values:http,https,ws,wss 高级特性认证时配置配置为true将在文档中隐藏返回的对象这些对象是有效的“List”，“Set”or “Map”，其他无效 “GET”、“HEAD”、“POST”、“PUT”、“DELETE”、“OPTIONS”and "PATCh" http的状态码默认200 扩展属性用于提示内容
@ApiImpliciParam	修饰方法中的参数	用在@ApiImplicitParams注解中对，指定一个请求参数的各个方面	paramType name value dataType required defaultValue	参数放在哪个地方参数代表的含义参数名称参数类型，有String/int，无用是否必要参数的默认值
@ApiImpliciParams	修饰方法中的参数	用在方法上包含一组参数说明	@ApiImpliciParam	ApiImpliciParam的数组集合
@ApiResponse	修饰方法的返回值	方法上或方法的参数上	code message class	方法返回值状态码方法返回值信息方法返回class
@ApiResponses	响应集配置	方法上或参数上	@ApiResponse	ApiResponse的数组集合
@ApiParam	映射方法上的参数	方法的参数上	name value defaultValue allowableValues required access allowMutiple hidden example	属性名称属性值默认属性值可以不配置是否属性必填不过多描述默认为false 隐藏该属性举例子
@ApiModel	用于类，表示对类进行说明，用于参数用实体类接受	类上	value description	类名描述
@ApiModelProperty	标识一个类的属性	类的字段上	value name dateType required example hidden	字段说明重写属性名字重写属性类型是否必填举例子隐藏

四：在项目中如何集成swagger？

①在controller中使用注解

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(value = "测试TTestController",tags = {"测试访问接口"})
@RequestMapping("test")

public class TTestController {

    @ApiOperation(value = "添加测试数据")
    @PostMapping("/insertInfo")
    @ApiResponses(value = {
            @ApiResponse(code = 1000,message = "成功"),
            @ApiResponse(code = 1001,message = "失败"),
            @ApiResponse(code = 1002,message = "缺少参数",response = TestUser.class)
    })
    public String insertInfo(@ApiParam("用户名字") @RequestParam("userName") String userName,
                             @ApiParam(value = "年龄",allowEmptyValue = true) @RequestParam("age") Integer age){
        String username = userName;
        Integer Age = age;
        return username+age.toString();
    }
}

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "testUser",description = "用户")
public class TestUser {

    @ApiModelProperty(value = "用户名字", name = "userName", dataType = "String")
    private String userName;

    private Integer age;

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public String getUserName() {
        return userName;
    }

    public void setUserName(String userName) {
        this.userName = userName;
    }
}

②访问本地链接

http://localhost:8080/swagger-ui.html

五：是那个用swagger需要注意的问题

①:对于只有一个HttpServletRequest参数的方法,如果参数小于5个，推荐使用 @ApiImplicitParams的方式单独封装每一个参数；如果参数大于5个，采用定义一个对象去封装所有参数的属性，然后使用@APiParam的方式

②默认的访问地址：ip:port/swagger-ui.html#/,但是在shiro中,会拦截所有的请求，必须加上默认访问路径（比如项目中，就是
ip:port/context/swagger-ui.html#/），然后登陆后才可以看到

③在GET请求中，参数在Body体里面,不能使用@RequestBody。在POST请求，可以使用@RequestBody和@RequestParam，如果使用@RequestBody，对于参数转化的配置必须统一

④ controller必须指定请求类型，否则swagger会把所有的类型(6种)都生成出来

⑤: swagger在生产环境不能对外暴露,可以使用@Profile({“dev”, “prod”,“pre”})指定可以使用的环境

六：总结

swagger作为一款辅助性的工具，能大大提升我们的和前端的沟通效率,接口是一个非常重要的传递数据的媒介，每个接口的签名、方法参数都非常重要。一个良好的文档非常重要，如果采用手写的方式非常容易拼写错误，而swagger可以自动化生成参数文档，这一切都加快了我们的沟通效率。并且可以替代postman的作用。实在是开发编程必备良品啊。

转载于:https://www.cnblogs.com/companionspace/p/10303064.html