您现在的位置是：首页 > 其他

当前栏目

swagger使用教程

教程 swagger 使用

2023-09-11 14:19:18 时间

1 Swagger 简介

翻译：大摇大摆;神气十足

读音： [ˈswæɡər] 人称：（丝袜哥）

版本：swagger3比swagger2相比,配置更少，使用更加方便

官网：https://swagger.io/ （API Development for Eveyone）

在线编辑器：http://editor.swagger.io/

作用：简单但功能强大的API表达工具

配置或修改源码，达到对应功能：

Swagger Codegen
Swagger UI
Swagger Editor
Swagger Inspector
Swagger Hub

2 使用

2.1 新建一个SpringBoot项目

目前版本使用 2.5.5
在这里插入图片描述

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.5.5</version>
</parent>

2.2 引入依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

整体个pom.xml如下

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>swagger</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
    </properties>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.5.5</version>
    </parent>

    <dependencies>
        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <!--web-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!--test-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>

            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>2.5.5</version>
                <configuration>
                    <!-- 如果没有该配置，热部署的devtools不生效 -->
                    <fork>true</fork>
                </configuration>
            </plugin>

        </plugins>
    </build>

</project>

2.3 开启Swagger

在SpringBoot的启动类添加**@EnableOpenApi**注解，开启Swagger支持

@EnableOpenApi
@SpringBootApplication
public class Starter extends SpringBootServletInitializer {
    public static void main(String[] args) {
        SpringApplication.run(Starter.class);
    }
}

2.4 新建 Controller.java控制器类

@RestController
public class HelloWorldController {

    @RequestMapping("/helloWorld")
    public String helloWorld(){
        return "helloWorld";
    }
}

@RestController注解相当于@ResponseBody ＋ @Controller合在一起的作用

2.5 启动测试

1 hello返回结果

localhost:8080/hello 没有问题可进行下一步
在这里插入图片描述

2 访问swagger-ui,查看接口文档

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

注意，这个网址一定路径要写齐全 http://localhost:8080/swagger-ui/

结构如下

分组定义信息区块
API文档上信息区块
接口定义信息区块

在这里插入图片描述

2.6 Swagger注解描述接口

@Api(tags="hello类测试")
@RestController
public class HelloController {

    @ApiOperation("测试方法")
    @RequestMapping("hello")
    public String hello(){
        return "helloWorld";
    }
}

效果
$[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-Ev7RFpmX-1640337152400)(E:\系统默认\桌面\CRM项目\img\image-20211224114720419.png)]$

3 常用配置注解

3.1 @Api

用于请求的类上，表示对类的说明

tags=“说明该类的作用，可以在ui界面上看到的注解”
value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”

3.2 @ApiOperation

用在请求的方法上，说明方法的用途、作用

value=“说明方法的用途、作用”
notes=“方法的备注说明”

3.3 @ApiImplicitParams

用在请求的方法上，表示一组参数说明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

name：参数名

value：参数的汉字说明、解释

required：参数是否必须传

paramType：参数放在哪个地方

header --> 请求参数的获取：@RequestHeader

query --> 请求参数的获取：@RequestParam

path（用于restful接口）–> 请求参数的获取：@PathVariable

div（不常用）

form（不常用）

dataType：参数类型，默认String，其它值dataType=“Integer”

defaultValue：参数的默认值

3.4 @ApiResponses：

用在请求的方法上，表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类

3.5 @ApiModel

用于响应类上，表示一个返回响应数据的信息

（这种一般用在post创建的时候，使用@RequestBody这样的场景，

请求参数无法使用@ApiImplicitParam注解进行描述的时候）

@ApiModelProperty：用在属性上，描述响应类的属性

3.6 实例一参数注释说明

@ApiImplicitParams
@ApiImplicitParam

@GetMapping("query")
@ApiImplicitParams({
        @ApiImplicitParam(name = "name",value = "姓名",required = true,paramType = "query"),
        @ApiImplicitParam(name = "age",value = "年龄",required = true,paramType = "query",dataType = "Integer")
})
@ApiOperation("测试查询")
public String search(String name,Integer age){
    return name+":"+age;
}

效果

$[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-K4haK5Et-1640337152402)(E:\系统默认\桌面\CRM项目\img\image-20211224152320499.png)]$

实例二实体注释说明

@ApiModel
@ApiModelProperty

新建 User类

@ApiModel("用户信息实体")
public class User {
    @ApiModelProperty("编码")
    private Integer id;

    @ApiModelProperty("姓名")
    private String name;

    @ApiModelProperty("年龄")
    private Integer age;

	/*get和set省略*/

    public User() {
    }

    public User(Integer id,String name, Integer age) {
        this.id=id;
        this.name = name;
        this.age = age;
    }

    @Override
    public String toString() {
        return "User{" +
                "id=" + id +
                ", name='" + name + '\'' +
                ", age=" + age +
                '}';
    }
}

controller类

@PostMapping("add")
@ApiOperation("测试添加")
public String add(User user){
    return user.getName()+":"+user.getAge();
}

效果

$[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-lQkS5p1f-1640337152403)(E:\系统默认\桌面\CRM项目\img\image-20211224152956506.png)]$

实例三响应码

@ApiResponses
@ApiResponse

@GetMapping("/user/{id}")
@ApiOperation("根据ID获取用户信息")
@ApiImplicitParams({@ApiImplicitParam(name="id",value = "用户编号",required = true,paramType ="path")})
@ApiResponses({
        @ApiResponse(code=408,message = "错误1" ),
        @ApiResponse(code=400,message = "错误2" ),
        @ApiResponse(code=404,message = "错误3" )
})
public User load(@PathVariable("id") Integer id){
    return new User(id,"jack",32);
}

效果
$[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-qi6oraDX-1640337152406)(E:\系统默认\桌面\CRM项目\img\image-20211224153426110.png)]$

接口测试

Swagger-ui图形客户端提供了接口测试功能；

点击-Try it out
点击-Execute

API信息配置

源码

springfox.documentation.service.ApiInfo.java
$[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-x72dzuL3-1640337152408)(E:\系统默认\桌面\CRM项目\img\image-20211224155554648.png)]$

static {
    DEFAULT = new ApiInfo(
    "Api Documentation", 
    "Api Documentation", 
    "1.0", 
    "urn:tos", 
    DEFAULT_CONTACT, 
    "Apache 2.0", 
    "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
}

springfox.documentation.spring.web.plugins.Docket.java
在这里插入图片描述

@Configuration
public class Swagger3Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)  // 指定swagger3.0版本
                .groupName("开发组001")
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.example.controller"))  // 指定扫描的包  常用方式
                .build()
                .apiInfo(createApiInfo());
    }

    @Bean
    public ApiInfo createApiInfo(){
        return new ApiInfo(
                "Api Documentation",  //标题
                "XX项目Api文档",//描述
                "3.0",             //版本
                "https://www.kszs.xyz",//团队链接
                new Contact("小明", "https://www.kszs.xyz", "123456789@qq.com"),
                "Apache 2.0",
                "https://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

在这里插入图片描述

这些API信息主要作用是让前端开发人员看的，谁开发的接口，或者那个小组负责，有问题方便联系沟通。

Docket开关|过滤|分组配置详解

开关设置 enable

开发环境才会用到swagger；正式环境需要关闭swagger;

原因：一个是安全问题，另外一个它会影响系统运行速度

enable

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.OAS_30)  // 指定swagger3.0版本
	/*其它省略*/
   .enable(false) //关闭
   .apiInfo(createApiInfo());
}

设置过滤

apis (必选有调用select) 参数：

any 所有都有效
none都无效
withClassAnnotation 根据类注解
withMethodAnnotation 根据方法注解
basePackage根据包路径（主要）

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.OAS_30)  // 指定swagger3.0版本
  /*其它省略先*/
  .select()
  .apis(RequestHandlerSelectors.basePackage("org.example.controller"))  
  .apiInfo(createApiInfo());
}

最后都要加build方法

还有一个 paths方法参数有

any 匹配任意路径
none都不匹配
regex正则匹配

.apis(RequestHandlerSelectors.basePackage("/org/example/**"))

设置分组

groupName

.groupName("开发组001")

结合过滤，通过apis的basePackage方法，弄2个组，分别扫描不同包路径，模拟分组开发

@GetMapping是一个组合注解，是@RequestMapping(method = RequestMethod.GET)的缩写

@PostMapping是一个组合注解，是@RequestMapping(method = RequestMethod.POST)的缩写

1、get方式的安全性较Post方式要差些，包含机密信息的话，建议用Post数据提交方式；
2、在做数据查询时，建议用Get方式；而在做数据添加、修改或删除时，建议用Post方式；

源码下载：https://download.csdn.net/download/Linlietao0587/70087229

1 在pom.xml 添加

    <!--15、jwt 用到-->
    <!--15、jwt 用到-->
    <dependency>
      <groupId>com.auth0</groupId>
      <artifactId>java-jwt</artifactId>
      <version>3.10.3</version>
    </dependency>
    <!--16、swagger3 用到-->
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-boot-starter</artifactId>
      <version>3.0.0</version>
    </dependency>

2 starter.java 添加

@EnableOpenApi

3 swaggerConfig
常用是有案例

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;
import java.util.List;

/**
 * Swagger3 配置设置
 */
@Configuration
public class Swagger3Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)  // 指定swagger3.0版本
                .groupName("开发组001")
                .select()
                .apis(RequestHandlerSelectors.basePackage("xyz.kszs.controller"))  // 指定扫描的包  常用方式
                .build()
                .enable(false) //开关
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts())
                .apiInfo(createApiInfo());
    }

    @Bean
    public ApiInfo createApiInfo(){
        return new ApiInfo(
                "Api Documentation",  //标题
                "kszs项目Api文档",          //描述
                "3.0",                     //版本
                "https://www.baidu.com",   //团队链接
                new Contact("林烈涛", "https://www.baidu.com", "123456789@qq.com"),
                "Apache 2.0",
                "https://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

    /**
     * 认证的安全上下文 Authorization
     */
    private List<SecurityScheme> securitySchemes() {
        List<SecurityScheme> securitySchemes = new ArrayList<>();
        securitySchemes.add(new ApiKey("token", "token", "header"));
        return securitySchemes;
    }

    /**
     * 授权信息全局应用
     */
    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.any()).build());
        return securityContexts;
    }

    /**
     * 可添加token
     */
    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("token", authorizationScopes));
        return securityReferences;
    }
}

猜你喜欢

android:keytool生成应用签名证书(java 15)
OpenGL ES 详解纹理生成和纹理映射步骤以及函数
03基础自绘-11开关按钮-switchbutton
Atitit.ioc 动态配置文件guice 设计原理
程序员的量化交易之路（27）--Cointrader之PriceData价格数据（14）
uni-app 前后端实战课 - 《悦读》学习笔记：【创建项目、后端环境介绍】小程序开发实例教程1/
PHP利用GD库处理图片方法实现
Java并发编程：Callable、Future和FutureTask
codeforces Restore Cube（暴力枚举）
【JavaScript】对象
MFC Windows 程序设计[166]之Tab选项卡控件(附源码)
Asp.net2.0之自定义控件ImageButton
L1-041 寻找250 (10 分)—团体程序设计天梯赛
C/C++学习笔记十二 Input and Output (I/O)（1）
D7 D2007 XE10.1 都支持的字符分隔函数
辨析element.offsetXxxx和element.style.xxxx

相关主题

Eclipse 教程
MySQL 教程下
SVN使用教程
HTML 教程
XSL简明教程
Spring boot教程
MySQL 使用教程
pycharm配置教程
PID教程
PostgreSQL教程
教程网大全
Fiddler 教程(转)
（二）教程
spring cloud教程
eclipse汉化教程

zl程序教程

当前栏目

swagger使用教程

1 Swagger 简介

2 使用

2.1 新建一个SpringBoot项目

2.2 引入依赖

2.3 开启Swagger

2.4 新建 Controller.java控制器类

2.5 启动测试

1 hello返回结果

2 访问swagger-ui,查看接口文档

2.6 Swagger注解描述接口

3 常用配置注解

3.1 @Api

3.2 @ApiOperation

3.3 @ApiImplicitParams

3.4 @ApiResponses：

3.5 @ApiModel

3.6 实例一参数注释说明

实例二实体注释说明

实例三响应码

接口测试

API信息配置

Docket开关|过滤|分组配置详解

开关设置 enable

设置过滤

设置分组

相关文章

当前栏目

swagger使用教程

1 Swagger 简介

2 使用

2.1 新建一个SpringBoot项目

2.2 引入依赖

2.3 开启Swagger

2.4 新建 Controller.java控制器类

2.5 启动测试

1 hello返回结果

2 访问swagger-ui,查看接口文档

2.6 Swagger注解描述接口

3 常用配置注解

3.1 @Api

3.2 @ApiOperation

3.3 @ApiImplicitParams

3.4 @ApiResponses：

3.5 @ApiModel

3.6 实例一 参数注释说明

实例二 实体注释说明

实例三 响应码

接口测试

API信息配置

Docket开关|过滤|分组 配置详解

开关设置 enable

设置过滤

设置分组

相关文章

3.6 实例一参数注释说明

实例二实体注释说明

实例三响应码

Docket开关|过滤|分组配置详解