Swagger 文档工具 设计、构建、文档化和使用您的 RESTful API

Swagger

Swagger 是一个功能强大的开源框架，支持大量工具生态系统，帮助您设计、构建、文档化和使用您的 RESTful API。

使用 SpringBoot

您可以从 swagger-springboot 获取完整的项目演示。

springboot-blog 中文版

文件结构可能如下所示：

.
|____main
| |____java
| | |____com
| | | |____ryo
| | | | |____Application.java
| | | | |____controller
| | | | | |____HelloWorld.java
| | | | |____Swagger2.java
| |____resources
| | |____application.properties
| | |____log4j2.xml
| | |____README.md

maven 配置

1、 创建 SpringBoot 项目

  • 在 pom.xml 中导入 SpringBoot 依赖包
<?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>com.ryo</groupId>
    <artifactId>springboot</artifactId>
    <version>1.0.0</version>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <plugin.tomcat.version>2.2</plugin.tomcat.version>
        <maven-surefire-plugin.version>2.18.1</maven-surefire-plugin.version>
        <maven-compiler-plugin.version>3.3</maven-compiler-plugin.version>

        <!--spring-boot-->
        <spring-boot.version>1.3.5.RELEASE</spring-boot.version>

        <log4j.version>2.6</log4j.version>
    </properties>

    <dependencies>
        <!--spring-boot-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <version>${spring-boot.version}</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <version>${spring-boot.version}</version>
        </dependency>

        <!--log4j-->
        <dependency>
            <groupId>org.apache.logging.log4j</groupId>
            <artifactId>log4j-api</artifactId>
            <version>${log4j.version}</version>
        </dependency>
        <dependency>
            <groupId>org.apache.logging.log4j</groupId>
            <artifactId>log4j-core</artifactId>
            <version>${log4j.version}</version>
        </dependency>

    </dependencies>


    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>${spring-boot.version}</version>
            </plugin>

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>${maven-surefire-plugin.version}</version>
                <configuration>
                    <skipTests>true</skipTests>
                    <testFailureIgnore>true</testFailureIgnore>
                </configuration>
            </plugin>

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>${maven-compiler-plugin.version}</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

2、maven 导入 jar

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
</dependency>

配置信息

我们可以定义一个 swagger 的全局配置。

package com.github.houbb.register.http.admin.config;

import org.springframework.context.annotation.Bean;
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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * swagger 配置
 *
 * @author binbin.hou
 * @since 1.0.0
 */
@EnableSwagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.github.houbb.register.http.admin.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(new ApiInfoBuilder()
                        .title("SpringBoot整合Swagger测试")
                        .description("SpringBoot整合Swagger，详细信息......")
                        .version("9.0")
                        .contact(new Contact("老马", "blog.csdn.net", "aaa@gmail.com"))
                        .license("The Apache License")
                        .licenseUrl("http://www.baidu.com")
                        .build());
    }

}

最核心的主要是 RequestHandlerSelectors.basePackage("com.github.houbb.register.http.admin.controller")

我们指定了需要扫描的包路径。

文档定义

3、配置使用

  • Application.java
package com.ryo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * Created by houbinbin on 16/6/5.
 */
@SpringBootApplication
public class Application {
    public static void main(String args[]) {
        SpringApplication.run(Application.class, args);
    }
}
  • HelloWorld.java
package com.ryo.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

/**
 * Created by houbinbin on 16/6/19.
 */
@RestController
@RequestMapping("hello")
@Api(value = "hello", description = "spring boot 初步测试")
public class HelloWorld {

    @ApiOperation(value="hello", notes="初步使用啦啦啦")
    @RequestMapping(method = RequestMethod.GET)
    public String hello() {
        return "SUCCESS";
    }
}
  • application.properties
server.port=180080

应用启动 & 访问

4、 启动应用

Maven Projects->${project}->Plugins->spring-boot->spring-boot:run

 .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::        (v1.3.5.RELEASE)

2016-12-25 15:29:50.066  INFO 4095 --- [           main] com.ryo.Application                      : Starting Application on houbinbindeMacBook-Pro.local with PID 4095 (/Users/houbinbin/IT/code/springboot/target/classes started by houbinbin in /Users/houbinbin/IT/code/springboot)
2016-12-25 15:29:50.069  INFO 4095 --- [           main] com.ryo.Application                      : No active profile set, falling back to default profiles: default
...
2016-12-25 15:29:52.688  INFO 4095 --- [           main] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat started on port(s): 18080 (http)
2016-12-25 15:29:52.692  INFO 4095 --- [           main] com.ryo.Application                      : Started Application in 3.094 seconds (JVM running for 5.262)
  • 浏览器访问

浏览器访问：http://localhost:8080/swagger-ui.html

基本配置例子

Controller 控制器

package com.github.houbb.register.http.admin.controller;


import com.github.houbb.register.http.admin.model.ClientLogDto;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.ResponseBody;

/**
 * <p>
 * 客户端数据日志 前端控制器
 * </p>
 *
 * @author binbin.hou
 * @since 2021-03-08
 */
@Controller
@RequestMapping("/clientLog")
@Api(tags = "客户端日志 CRUD")
public class ClientLogController {

    @PostMapping("/add")
    @ApiOperation("添加日志")
    @ResponseBody
    public String add(ClientLogDto clientLogDto) {
        System.out.println(clientLogDto);
        return "ok";
    }

}

实体属性

针对入参 ClientLogDto，我们可以添加对应的属性描述如下：

public class ClientLogDto implements Serializable {

    @ApiModelProperty(value = "类型")
    private String type;

    @ApiModelProperty(value = "地址")
    private String ip;

    @ApiModelProperty(value = "名称")
    private String name;

    //getter & setter & toString()
}

效果

重新启动应用，效果如下：

输入图片说明

测试

我们可以使用 【Try it out】，可以进行相关的测试。

输入图片说明

点击 execute 按钮，可以获取非常详细的文档返回。

常用注解说明

  1. @Api注解可以用来标记当前Controller的功能。

  2. @ApiOperation注解用来标记一个方法的作用。

  3. @ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。

  4. 如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。

  5. 需要注意的是，@ApiImplicitParam注解中虽然可以指定参数是必填的，但是却不能代替@RequestParam(required = true)，前者的必填只是在Swagger2框架内必填，抛弃了Swagger2，这个限制就没用了，所以假如开发者需要指定一个参数必填，@RequestParam(required = true)注解还是不能省略。

  6. 如果参数是一个对象（例如上文的更新接口），对于参数的描述也可以放在实体类中。

一点思考

swagger2 的 ui 还是非常舒服的，功能也比较强大，不过有一点比较可惜，那就是注解显得有一点点冗余。

可以考虑配合 yAPI 使用。

参考资料

SpringBoot的整合（四、整合Swagger2）

SpringBoot swagger 配置账号密码

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：/a/498456.html

如若内容造成侵权/违法违规/事实不符，请联系我们进行投诉反馈qq邮箱809451989@qq.com，一经查实，立即删除！

相关文章

基于多模态信息的语音处理(misp) 2023挑战:视听目标说话人提取

基于多模态信息的语音处理(misp) 2023挑战:视听目标说话人提取

THE MULTIMODAL INFORMATION BASED SPEECH PROCESSING (MISP) 2023 CHALLENGE: AUDIO-VISUAL TARGET SPEAKER EXTRACTION 第二章 目标说话人提取之《基于多模态信息的语音处理(misp) 2023挑战:视听目标说话人提取》 文章目录 THE MULTIMODAL INFORMATION BASED SPEECH PROCESS…
阅读更多...
Synchronized锁、公平锁、悲观锁乐观锁、死锁等

Synchronized锁、公平锁、悲观锁乐观锁、死锁等

悲观锁 认为自己在使用数据的时候一定会有别的线程来修改数据，所以在获取数据前会加锁，确保不会有别的线程来修改 如： Synchronized和Lock锁 适合写操作多的场景 乐观锁 适合读操作多的场景 总结： 线程8锁🔐 调用 声明 结果：先打印发送短信，后打印发送邮件 结论…
阅读更多...
FPGA 图像边缘检测（Canny算子）

FPGA 图像边缘检测（Canny算子）

1 顶层代码 timescale 1ns / 1ps //边缘检测二阶微分算子&#xff1a;canny算子module image_canny_edge_detect (input clk,input reset, //复位高电平有效input [10:0] img_width,input [ 9:0] img_height,input [ 7:0] low_threshold,input [ 7:0] high_threshold,input va…
阅读更多...
uniapp 中引入第三方组件后,更改组件的样式 -使用/deep/不生效

uniapp 中引入第三方组件后,更改组件的样式 -使用/deep/不生效

在我们使用Vue搭建项目的时候&#xff0c;我们经常会用到一些UI框架&#xff0c;如Element&#xff0c;iView&#xff0c;但是有时候我们又想去修改Ul框架的样式&#xff0c;当我们修改样式失败的时候&#xff0c;可以尝试一下/deep/&#xff0c;亲测有效。 那失败的原因是什么…
阅读更多...
基于DBO-CNN-BiLSTM数据回归预测(多输入单输出)，蜣螂优化算法优化CNN-BiLSTM-附代码

基于DBO-CNN-BiLSTM数据回归预测(多输入单输出)，蜣螂优化算法优化CNN-BiLSTM-附代码

基于DBO-CNN-BiLSTM的数据回归预测是一种综合利用了深度学习中的多种技术的方法&#xff0c;包括卷积神经网络&#xff08;CNN&#xff09;、双向长短期记忆网络&#xff08;BiLSTM&#xff09;和注意力机制&#xff08;Attention&#xff09;。蜣螂优化算法用于优化CNN-BiLSTM…
阅读更多...
揭秘’在家答答题，无需经验、无论男女、单号轻松日产200+的一个玩法

揭秘’在家答答题，无需经验、无论男女、单号轻松日产200+的一个玩法

项目简介 公众号&#xff1a;老A程序站 这个项目是人人可参与的&#xff0c;无需支付任何费用&#xff0c;只需投入时间即可。每天的任务主要是回答问题。 项目 地 址 &#xff1a; laoa1.cn/1457.html 如果遇到不会的问题&#xff0c;可以直接使用百度进行搜索。我们通过…
阅读更多...
【明道云】如何让用户可以新增但不能修改记录

【明道云】如何让用户可以新增但不能修改记录

【背景】 遇到一个需求场景&#xff0c;用户希望新增数据后锁住数据不让更改。 【分析】 在设计表单时直接将字段设置只读是不行的。字段设置只读将会直接让界面上此字段的前端组件不可编辑。包括新增时也无法填入。显然是不符合需求的。 需要既能新增&#xff0c;新增后又不…
阅读更多...
5.6 物联网RK3399项目开发实录-Android开发之U-Boot 编译及使用（wulianjishu666）

5.6 物联网RK3399项目开发实录-Android开发之U-Boot 编译及使用（wulianjishu666）

物联网入门到项目实干案例下载&#xff1a; https://pan.baidu.com/s/1fHRxXBqRKTPvXKFOQsP80Q?pwdh5ug --------------------------------------------------------------------------------------------------------------------------------- U-Boot 使用 前言 RK U-B…
阅读更多...
在香港服务器搭网站速度怎么样？

在香港服务器搭网站速度怎么样？

在香港服务器搭网站速度怎么样&#xff1f;一般要看用户所在地理位置&#xff0c;如果用户距离香港服务器较远&#xff0c;网络延迟会增加&#xff0c;导致加载速度变慢。 面对海外地区用户&#xff0c;香港作为亚洲连接海外的网络中转枢纽&#xff0c;多条国际海底电缆&#…
阅读更多...
编译原理知识点整理

编译原理知识点整理

第一章 绪论 计算机语言发展历程 第一代语言&#xff1a;机器语言第二代语言&#xff1a;汇编语言第三代语言&#xff1a;高级语言(如C&#xff0c;C&#xff0c;Java等)第四代语言&#xff1a;极高级领域语言(如SQL)第五代语言&#xff1a;可视化配置语言第六代语言&#xff…
阅读更多...
抢先看！界面控件DevExpress WPF 2024产品路线图预览（一）

抢先看！界面控件DevExpress WPF 2024产品路线图预览（一）

DevExpress WPF拥有120个控件和库&#xff0c;将帮助您交付满足甚至超出企业需求的高性能业务应用程序。通过DevExpress WPF能创建有着强大互动功能的XAML基础应用程序&#xff0c;这些应用程序专注于当代客户的需求和构建未来新一代支持触摸的解决方案。 本文将介绍2024年Dev…
阅读更多...
事件穿透效果

事件穿透效果

讲述一下事件穿透的需求&#xff0c;大家可以根据实际情况来考虑是否采用这种方式来制作页面&#xff0c;&#xff08;项目中遇到了底部是地图&#xff0c;两侧面板&#xff0c;但是UI在设计的时候为了好看&#xff0c;会有很大的遮罩阴影部分&#xff0c;如果按照时间制作会导…
阅读更多...
图书推荐|Bootstrap 5从入门到精通：视频教学版

图书推荐|Bootstrap 5从入门到精通：视频教学版

示例源码、PPT课件、同步教学视频、作者微信答疑、教学大纲、其他丰富的教学资源 本书内容 《Bootstrap 5从入门到精通&#xff1a;视频教学版》结合示例和综合项目的演练&#xff0c;详细讲解Bootstrap开发技术&#xff0c;使读者快速掌握Bootstrap开发技能&#xff0c;提高使…
阅读更多...
[SpringCloud] Feign Client 的创建 (二) (五)

[SpringCloud] Feign Client 的创建 (二) (五)

文章目录 1.自动配置FeignAutoConfiguration2.生成 Feign Client2.1 从Feign Client子容器获取组件2.2 Feign Client子容器的创建2.3 构建Feign Client实例 1.自动配置FeignAutoConfiguration spring-cloud-starter-openfeign 包含了 spring-cloud-openfeign-core FeignAutoCo…
阅读更多...
CSS实现小车旅行动画实现

CSS实现小车旅行动画实现

小车旅行动画实现 效果展示 CSS 知识点 灵活使用 background 属性下的 repeating-linear-gradient 实现路面效果灵活运用 animation 属性与 transform 实现小车和其他元素的动画效果 动画场景分析 从效果图可以看出需要实现此动画的话&#xff0c;需要position属性控制元素…
阅读更多...
机器学习(三)

机器学习(三)

神经网络: 神经网络是由具有适应性的简单单元组成的广泛并行互连的网络&#xff0c;它的组织能够模拟生物神经系统对真实世界物体所作出的交互反应。 f为激活(响应)函数: 理想激活函数是阶跃函数&#xff0c;0表示抑制神经元而1表示激活神经元。 多层前馈网络结构: BP(误差逆…
阅读更多...
微服务demo（二）nacos服务注册与集中配置

微服务demo（二）nacos服务注册与集中配置

环境&#xff1a;nacos1.3.0 一、服务注册 1、pom&#xff1a; 移步spring官网https://spring.io&#xff0c;查看集成Nacos所需依赖 找到对应版本点击进入查看集成说明 然后再里面找到集成配置样例&#xff0c;这里只截一张&#xff0c;其他集成内容继续向下找 我的&#x…
阅读更多...
【Python】python+requests+excel+unittest+ddt实现接口自动化实例

【Python】python+requests+excel+unittest+ddt实现接口自动化实例

目录 测试需求实现思路框架代码实例1. 环境准备和配置文件2. Excel接口数据及测试结果3. API封装4. 读取Excel数据5. 测试用例6. 日志和配置文件处理7. HTMLTestRunner生成可视化的html报告8. 报告通过飞书/邮件发送报告通过飞书发送报告通过邮件发送9. 入口函数10. 飞书Webhoo…
阅读更多...
Day46：WEB攻防-注入工具SQLMAPTamper编写指纹修改高权限操作目录架构

Day46：WEB攻防-注入工具SQLMAPTamper编写指纹修改高权限操作目录架构

目录 数据猜解-库表列数据&字典 权限操作-文件&命令&交互式 提交方法-POST&HEAD&JSON 绕过模块-Tamper脚本-使用&开发 分析拓展-代理&调试&指纹&风险&等级 知识点&#xff1a; 1、注入工具-SQLMAP-常规猜解&字典配置 2、注入…
阅读更多...
Nagios工具

Nagios工具

一 nagios 相关概念 Nagios 是一款开源的免费网络监视工具&#xff0c;能有效监控 Windows、Linux 和 Unix 的主机状态&#xff0c;交换机路由器等网络设置&#xff0c;打印机等。在系统或服务状态异常时发出邮件或短信报警第 一时间通知网站运维人员&#xff0c;在状态恢复后…
阅读更多...
最新文章

Copyright @ 2022~2023