zoukankan      html  css  js  c++  java
  • 【一篇文章就够了】web文档神器——Swagger2

    简介

    Spring Boot 框架是目前非常流行的微服务框架,我们很多情况下使用它来提供 Rest API。而对于 Rest API 来说很重要的一部分内容就是文档,Swagger 为我们提供了一套通过代码和注解自动生成文档的方法,这一点对于保证 API 文档的及时性将有很大的帮助。本文将使用 Swagger 2 规范的 Springfox 实现来了展示如何在 Spring Boot 项目中使用 Swagger,主要包含了如何使用 Swagger 自动生成文档、使用 Swagger 文档以及 Swagger 相关的一些高级配置和注解。


    链接:https://developer.ibm.com/zh/articles/j-using-swagger-in-a-spring-boot-project/
    著作权归作者所有。商业转载请联系作者获得授权,非商业转载请注明出处。

    Demo

    第一步:创建一个SpringBoot项目
    这就不多说了
    第二步:导入依赖

    <!--    swagger依赖-->
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.9.2</version>
            </dependency>
    <!--        swaggerUI-->
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.9.2</version>
            </dependency>
    

    第三步:创建接口

    如图所示创建Java文件

    Swagger打错了,QAQ

    1. SwaggerConfig
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
        @Bean
        public Docket api() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .select()
                    .apis(RequestHandlerSelectors.any())
                    .paths(PathSelectors.any())
                    .build();
        }
    }
    

    @Configuration 是告诉 Spring Boot 需要加载这个配置类, @EnableSwagger2 是启用 Swagger2。

    还可以配置一些信息

    @Bean
        public Docket api() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .select()
                    .apis(RequestHandlerSelectors.any())
                    .paths(PathSelectors.any())
                    .build()
                    .apiInfo(apiInfo());
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfo(
                    "Spring Boot 项目集成 Swagger 实例文档",
                    "我的博客网站:https://itweknow.cn,欢迎大家访问。",
                    "API V1.0",
                    "Terms of service",
                    new Contact("名字想好没", "https://itweknow.cn", "gancy.programmer@gmail.com"),
                    "Apache", "http://www.apache.org/", Collections.emptyList());
        }
    

    配置之后,UI界面就会如下图所示

    1. UserController
    @RestController
    @RequestMapping("/user")
    public class UserController {
    
        @PostMapping("/add")
        public boolean addUser(@RequestBody User user) {
            return false;
        }
        @GetMapping("/find/{id}")
        public User findById(@PathVariable("id") int id) {
            return new User();
        }
        @PutMapping("/update")
        public boolean update(@RequestBody User user) {
            return true;
        }
    
    }
    

    这个很简单,不多说
    3. User
    同样不多说

    第四步:查看

    方法一:运行项目,打开链接:http://localhost:8080/v2/api-docs。但是这样查看的是json文件,没啥用。
    方法二:通过http://localhost:8080/swagger-ui.html,打开swagger的UI界面,如下图。

    接口过滤

    1. @ApiIgnore
      如果想在文档中屏蔽掉删除用户的接口(user/delete),那么只需要在删除用户的方法上加上 @ApiIgnore 即可。
    @ApiIgnore
    public boolean delete(@PathVariable("id") int id)
    
    1. 在 Docket 上增加筛选。Docket 类提供了 apis() 和 paths() 两个方法来帮助我们在不同级别上过滤接口:

    apis() :这种方式我们可以通过指定包名的方式,让 Swagger 只去某些包下面扫描。
    paths() :这种方式可以通过筛选 API 的 url 来进行过滤。
    在集成 Swagger2 的章节中我们这两个方法指定的都是扫描所有,没有指定任何过滤条件。如果我们在我们修改之前定义的 Docket 对象的 apis() 方法和 paths() 方法为下面的内容,那么接口文档将只会展示 /user/add 和 /user/find/{id} 两个接口。

    .apis(RequestHandlerSelectors.basePackage("cn.itweknow.sbswagger.controller"))
    .paths(Predicates.or(PathSelectors.ant("/user/add"),
            PathSelectors.ant("/user/find/*")))
    

    自定义响应消息

    Swagger 允许我们通过 Docket 的 globalResponseMessage() 方法全局覆盖 HTTP 方法的响应消息,但是首先我们得通过 Docket 的 useDefaultResponseMessages 方法告诉 Swagger 不使用默认的 HTTP 响应消息,假设我们现在需要覆盖所有 GET 方法的 500 和 403 错误的响应消息,我们只需要在 SwaggerConfig.java 类中的 Docket Bean 下添加如下内容:

    .useDefaultResponseMessages(false)
                    .globalResponseMessage(RequestMethod.GET, new ArrayList() {{
                        add(new ResponseMessageBuilder()
                                .code(500)
                                .message("服务器发生异常")
                                .responseModel(new ModelRef("Error"))
                                .build());
                        add(new ResponseMessageBuilder()
                                .code(403)
                                .message("资源不可用")
                                .build());
                    }});
    

    添加如上面的代码后,如下图所示,您会发现在 SwaggerUI 页面展示的所有 GET 类型请求的 403 以及 500 错误的响应消息都变成了我们自定义的内容。

    Swagger UI 的使用

    1.接口查看

    SwaggerUI 会以列表的方式展示所有扫描到的接口,初始状态是收缩的,我们只需要点击展开就好,而且会在左边标识接口的请求方式(GET、POST、PUT、DELETE 等等)。

    2.接口调用

    如下图所示,点击接口展开后页面右上角的 Try it out 按钮后,页面会变成如图所示:

    SwaggerUI 会给我们自动填充请求参数的数据结构,我们需要做的只是点击 Execute 即可发起调用

    3.Model

    如下图所示,SwaggerUI 会通过我们在实体上使用的 @ApiModel 注解以及 @ApiModelProperty 注解来自动补充实体以及其属性的描述和备注。

    注解详解

    1. @Api
      通过在控制器类上增加 @Api 注解,可以给控制器增加描述和标签信息。
    @Api(tags = "用户相关接口", description = "提供用户相关的 Rest API")
    public class UserController
    

    @Api其它属性配置:

    1. @ApiOperation
      通过在接口方法上增加 @ApiOperation 注解来展开对接口的描述,当然这个注解还可以指定很多内容,我们在下面的相关注解说明章节中详细解释。
    @ApiOperation("新增用户接口")
    @PostMapping("/add")
    public boolean addUser(@RequestBody User user) {
        return false;
    }
    

    @ApiOperation其它属性配置:

    2.1 @ApiImplicitParams、@ApiImplicitParam

    @ApiIgnore: Swagger 文档不会显示拥有该注解的接口。 @ApiImplicitParams: 用于描述接口的非对象参数集。 @ApiImplicitParam: 用于描述接口的非对象参数,一般与 @ApiImplicitParams 组合使用。

    @ApiImplicitParams:用在请求的方法上,包含一组参数说明
    	@ApiImplicitParam:对单个参数的说明	    
    	    name:参数名
    	    value:参数的说明、描述
    	    required:参数是否必须必填
    	    paramType:参数放在哪个地方
    	        · query --> 请求参数的获取:@RequestParam
    	        · header --> 请求参数的获取:@RequestHeader	      
    	        · path(用于restful接口)--> 请求参数的获取:@PathVariable
    	        · body(请求体)-->  @RequestBody User user
    	        · form(普通表单提交)	   
    	    dataType:参数类型,默认String,其它值dataType="Integer"	   
    	    defaultValue:参数的默认值
    

    实例

    @Api(tags="用户模块")
    @Controller
    public class UserController {
    
    	@ApiOperation(value="用户登录",notes="随边说点啥")
    	@ApiImplicitParams({
    		@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
    		@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
    		@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
    	})
    	@PostMapping("/login")
    	public JsonResult login(@RequestParam String mobile, @RequestParam String password,
    	@RequestParam Integer age){
    		//...
    	    return JsonResult.ok(map);
    	}
    }
    

    2.2 @ApiResponses、@ApiResponse

    @ApiResponses:方法返回对象的说明
    	@ApiResponse:每个参数的说明
    	    code:数字,例如400
    	    message:信息,例如"请求参数没填好"
    	    response:抛出异常的类
    

    实例

    @Api(tags="用户模块")
    @Controller
    public class UserController {
    
    	@ApiOperation("获取用户信息")
    	@ApiImplicitParams({
    		@ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户Id")
    	}) 
    	@ApiResponses({
    		@ApiResponse(code = 200, message = "请求成功"),
    		@ApiResponse(code = 400, message = "请求参数没填好"),
    		@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    	}) 
    	@ResponseBody
    	@RequestMapping("/list")
    	public JsonResult list(@RequestParam String userId) {
    		...
    		return JsonResult.ok().put("page", pageUtil);
    	}
    }
    
    1. @ApiModel 和 @ApiModelProperty
      @ApiModel: 可设置接口相关实体的描述。 @ApiModelProperty: 可设置实体属性的相关描述。
    @ApiModel("用户实体")
    public class User {
        @ApiModelProperty("用户 id")
    private int id;
    }
    

    参考文献
    https://www.jianshu.com/p/6d2beb9dec72
    https://blog.csdn.net/xiaojin21cen/article/details/78654652
    https://developer.ibm.com/zh/articles/j-using-swagger-in-a-spring-boot-project/

  • 相关阅读:
    前端开发聚合
    6. webRTC
    14.移动端图片浏览组件 react-wx-images-viewer
    windows下怎样使用md命令一次建立多级子目录
    mysql打印输出转csv格式
    Java Stream简介, 流的基本概念
    Linux使用Shell脚本实现ftp的自动上传下载
    在Linux中设置UMASK值
    SFTP+OpenSSH+ChrootDirectory设置
    导出php5.4支持的数组格式,即以[]为标识符而不是以array()标识
  • 原文地址:https://www.cnblogs.com/zllk/p/13713699.html
Copyright © 2011-2022 走看看