2020-08-27

标签: SpringBoot整合Swagger  spring boot

SpringBoot整合Swagger文档

简介

优点

后端根据swagger语法,自动生成漂亮规范的接口文档。

做交互测试。
劣势

侵入式的,影响程序运行,尤其是传参的时候。
注意

swagger 分1.2版本和2.0版本,差异较大。swagger1.2 即 swagger-ui ; swagger2.0 即 springfox-swagger 。本文介绍的使用方式是新的版本,即 springfox-swagger 。

发布生产,关闭swagger,以防泄漏项目接口文档,被攻击

常用注解说明

swagger 通过注解接口生成文档,包括接口名,请求方法,参数,返回信息等。

@Api: 修饰整个类,用于controller类上

@ApiOperation: 描述一个接口,用户controller方法上

@ApiParam: 单个参数描述

@ApiModel: 用来对象接收参数,即返回对象

@ApiModelProperty: 对象接收参数时,描述对象的字段

@ApiResponse: Http响应其中的描述,在ApiResonse中

@ApiResponses: Http响应所有的描述,用在

@ApiIgnore: 忽略这个API

@ApiError: 发生错误的返回信息

@ApiImplicitParam: 一个请求参数

@ApiImplicitParam: 多个请求参数

DemoApplication.java

  1. package com.example;

    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 注解,让 Spring 来加载该类配置。 //再通过 @EnableSwagger2 注解来启用
    Swagger2。 @Configuration @EnableSwagger2 public class DemoSwagger {
    @Bean
    public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
    .apiInfo(apiInfo())
    .select()
    // 指定要扫描的包路径
    .apis(RequestHandlerSelectors.basePackage(“com.example.controller”))
    .paths(PathSelectors.any())
    .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("项目api文档")
                .description("swagger接入教程")
                .version("1.0")
                .build();
    } }
    

    因为之前已经配置好了spring security,所以浏览器网址中输入
    http://localhost:8080/swagger-ui.html 后,会被拦截住,输入之前配置好的用户密码后,效果如下所示;
    在这里插入图片描述
    在这里插入图片描述

    因为之前测试用户登录,用户权限,所以controller里面已经有了一些接口方法,但是就让它这样默认,显然用户体验不好,所以在之前的userController里继续加上swagger的注解。

    @Api:用在类上,说明该类的作用。

    @ApiOperation:说明该方法的作用。

    具体而更细致的注解参见官方文档 常用注解说明 。

    UserController.java

    package com.example.controller;

    import io.swagger.annotations.Api; import
    io.swagger.annotations.ApiOperation; import
    org.springframework.stereotype.Controller; import
    org.springframework.web.bind.annotation.RequestMapping; import
    org.springframework.web.bind.annotation.RequestMethod; import
    org.springframework.web.bind.annotation.ResponseBody;

    @Controller @RequestMapping(“user”) @Api(value = “用户模块说明”,
    description = “提供用户的增、删、改、查”) public class UserController {

    @RequestMapping(value = "/addUser", method = RequestMethod.GET)
    @ResponseBody
    @ApiOperation(value = "添加用户", notes = "放一些信息,供测试判断")
    String addUser() {
        return "这是添加用户!!!";
    }
    
    @RequestMapping(value = "/deleteUser", method = RequestMethod.POST)
    @ResponseBody
    @ApiOperation(value = "删除用户", notes = "放一些信息,供测试判断")
    String deleteUser() {
        return "这是删除用户!!!";
    }
    
    @RequestMapping("/updateUser")
    @ResponseBody
    @ApiOperation(value = "修改用户", notes = "放一些信息,供测试判断")
    String updateUser() {
        return "这是修改用户!!!";
    }
    
    @RequestMapping(value = "/findAllUsers", method = RequestMethod.PUT)
    @ResponseBody
    @ApiOperation(value = "查询用户", notes = "放一些信息,供测试判断")
    String findAllUsers() {
        return "这是查询用户!!!";
    }
    

    }

    效果图如下
    在这里插入图片描述
    效果图如下在这里插入图片描述

具体打开某一条,如下
在这里插入图片描述

  1. 很明显,有了中文注释,文档可读性更强。

    要说明的是,平时写 @RequestMapping
    注解的时候,我通常会简写,如上demo中的修改用户方法。但是swagger是侵入式的,如果未指定 RequestMethod
    类型,就会把一大堆都列出来,如GET,HEAD,POST,PUT,DELETE,OPTIONS,PATCH ,而其他指定好的,则是一条。
    
版权声明:本文为weixin_46884775原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明。
本文链接:https://blog.csdn.net/weixin_46884775/article/details/108256309

智能推荐

java调用其他java项目的Https接口

项目中是这样的: 用户拿出二维码展示,让机器识别二维码, 机器调用开门的后台系统接口, 然后开门的后台系统接口需要调用管理系统的接口, 管理系统需要判断能不能开门.这两个系统是互相独立的.当时使用http调用是没有问题的.当时后来要求必须用https.废话不说,直接代码: 我的项目中调用的是 HttpsUtils.Get(utlStr) 这个接口 开门系统接口如下图:   管理系统的接口...

Hadoop1.2.1全分布式模式配置

一 集群规划 主机名            IP                               安装的软件 &nbs...

Go语言gin框架的安装

尝试安装了一下gin,把遇到的一些小问题来记录一下 安装步骤 首先来看看官方文档,链接点这里 可以看到安装步骤很简单,就一句话 在命令行中输入这句话运行等待就好。 问题来了,因为墙的问题,go get会很慢,所以命令行里面半天什么反应也没有,不要急,慢慢等着就会看到gin-gonic/gin这个目录出现 这个时候命令行还是没有结束,表示还在下一些东西。有的时候可能心急的人就停了(比如我),然后写个...

uni-app表单组件二

input(输入框) 属性名 类型 说明 平台差异 value String 输入框的初始内容 type String input 的类型 password Boolean(默认false) 是否是密码类型 placeholder String 输入框为空时占位符 placeholder-style String 指定 placeholder 的样式 placeholder-class Strin...

深入理解 JavaScript 代码执行机制

深入理解 JavaScript 代码执行机制 前言 本文仅为个人见解,如有错误的地方欢迎留言区探讨和指正。 1、餐前甜品 如下是一段 JavaScript 代码,如果你毫不犹豫的说出代码执行顺序。那么请直接滚动到底部,留下你的足迹,接受膜拜。如果还不是很确定,那么请往下继续查看。 2、磨刀不误砍柴工(了解浏览器原理) (1) 进程和线程 进程是cpu资源分配的最小单位(是能拥有资源和独立运行的最小...

猜你喜欢

Centos7下配置DRBD Cluster扩展节点

操作环境 CentOS Linux release 7.4.1708 (Core) DRBDADM_BUILDTAG=GIT-hash:\ ee126652638328b55dc6bff47d07d6161ab768db\ build\ by\ [email protected]\,\ 2018-07-30\ 22:23:07 DRBDADM_API_VERSION=2 DRBD_KERNEL_VER...

选择排序了解一下

选择排序是一种简单直观的排序算法,它的主要思想:初始时在序列中找到最小(大)的元素,放到序列的起始位置作为已排序序列;然后再从剩余未排序元素中继续寻找最小(大)的元素,放到已排序序列的末尾,以此类推,直到所有元素均排序完毕。 即每遍历一次就记住了最大(小)的元素的位置,最后仅需要一次交换操作就可以放到其适合的位置。 如下图所示: 实现代码如下: 选择排序是不稳定排序,时间复杂度在最优、最坏情况下都...

ssh免密登录、操作另一个服务器

目录 一、SSH简介 scp 传输文件 二、SSH免密登陆原理  三、SSH免密登陆 1、生成** 2、将客户端公钥 配置到服务器端 方法一:  方法二: 3、known_hosts 一、SSH简介 SSH(Secure Shell)是一种通信加密的网络传输协议,可在不安全的网络中为网络服务提供安全的传输环境。 SSH通过在网络中创建安全隧道来实现SSH客户...

如何把OpenCV v3.1.0整合到 Android Studio v1.4.1

本文翻译自: https://stackoverflow.com/questions/27406303/opencv-in-android-studio   点击打开链接 有经验的Android studio 开发大牛们可能觉得这篇文章写得太啰嗦,可是本文主要针对刚刚迈入进来的小妞们~~现在开始啦: 第一步 创建一个新工程(File/New Project) 命名为 "...