不用在写这么多的接口文档-SpringBoot整合Swagger,解放你打接口文档的双手

本文主要是介绍不用在写这么多的接口文档-SpringBoot整合Swagger,解放你打接口文档的双手,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

今天学习了一下Swagger的继承文档功能

我们为什么要使用Swagger呢?

在前后端通过分离的方式开发项目时,我们作为后端程序员,需要给予前端各种各样的接口,但是前端是不懂得代码的,所以我们在进行接口开发之后,还需要为接口写入一个文档,单独为接口介绍,使得前端人员能够通过此介绍方式在前端页面能够调用我们后台的控制器,而有时候在开发时,因为某些因素的变化,我们就需要对接口进行改变,那时,我们又需要重新修改接口并且还要重写我们给与前端的接口介绍文档,这样就使得我们的开发变得十分的麻烦,因此,Swagger框架就为此功能而生成了。

在使用Swagger的之前,我们首先使用手写的接口介绍尝试一次

--------------------------------------------------------------------------

接口:用户登录

接口路径:localhost:9999/dologin

请求参数:userName,password

参数名称参数类型注释
userNameString用户名
passwordString密码

请求方式:post

返回的数据结构

1 或者 2

1表示登录成功在数据库中有数据

2表示登录失败在数据库中没有数据

参数说明:

参数名称参数类型注释
IntegerInteger返回1表示登录成功 2表示登录失败

接口:删除用户

接口路径:localhost:9999/removeUser

请求参数:id

参数名称参数类型注释
idInteger用户的id编号

请求方式:get

返回的数据结构:

Integer

1或者0

参数说明

返回参数名称参数类型注释
Integer数据Integer返回1表示删除成功

接口:查询学生

接口路径:localhost:9004/student

请求参数:无

请求方式:get

返回的数据结构:

[{"studentNo": 1,"studentName": "张三","studentAge": 18,"studentSex": "男"},{"studentNo": 2,"studentName": "小花","studentAge": 17,"studentSex": "女"},{"studentNo": 3,"studentName": "小鲸鱼","studentAge": 10,"studentSex": "女"},{"studentNo": 4,"studentName": "大鲨鱼","studentAge": 16,"studentSex": "男"},{"studentNo": 5,"studentName": "大脑虎","studentAge": 20,"studentSex": "男"}
]

参数说明

参数名称参数类型注释
studentNoInteger学生编号
studentNameString姓名
studentAgeString年龄
studentSexString性别

接口:返回一个map集合

接口路径:localhost:9004/map

请求参数:无

请求方式:get

返回的数据结构:

{
"其一":“劝君莫惜金缕衣,劝君须惜少年时。有花堪折直须折,莫待无花空折枝。”,
"金缕衣":“杜秋娘”,
"其二":"青天无云月如烛,露泣梨花白如玉。 子规一夜啼到明,美人独在空房宿。"
}

参数说明

返回参数名称参数类型注释
map的key值String返回map集合的key值
map的value值String返回map集合的value值

---------------------------------------------------------------------------

本次我写入了四个接口介绍 感觉十分的麻烦,并且在写的过程中也遇到过代码不小心错误的问题。而这些问题如果是放到上百个接口以上的项目时,就容易极大的增加我们的工作量,这时,Swagger的好处就体现出来了。

使用 Swagger 集成文档具有以下几个优势:

  • 功能丰富 :支持多种注解,自动生成接口文档界面,支持在界面测试API接口功能;
  • 及时更新 :开发过程中花一点写注释的时间,就可以及时的更新API文档,省心省力;
  • 整合简单 :通过添加pom依赖和简单配置,内嵌于应用中就可同时发布API接口文档界面,不需要部署独立服务。

使用Swagger:

1.添加他的相关依赖

WEB依赖

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId>
</dependency>

swagger依赖,这里选择 2.9.2 版本。

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

添加配置类

添加一个swagger 配置类,在工程下新建 config 包并添加一个 SwaggerConfig 配置类。

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
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket createRestApi(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build();}private ApiInfo apiInfo(){return new ApiInfoBuilder().title("Kitty API Doc").description("This is a restful api document of Kitty.").version("1.0").build();}}

在添加完配置文件后,即代表Swagger已经配置成功了,我们接下来就

添加一个控制器 测试一下Swagger

添加一个控制器,在工程下新建 controller包并添加一个 HelloController控制器。

HelloController.java

package com.louis.springboot.demo.controller;import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;/* 类注解 */
@Api(value = "desc of class")
@RestController
public class HelloController {/* 方法注解 */@ApiOperation(value = "desc of method", notes = "")@GetMapping(value="/hello")public Object hello( /* 参数注解 */ @ApiParam(value = "desc of param" , required=true ) @RequestParam String name) {return "Hello " + name + "!";}
}

添加完成后,我们启动一下项目

启动完成后

我们在浏览器中收入我们的http://localhost:8080/swagger-ui.html#/
加入swagger-ui中 可以看到我们创建的控制器就在此页面呈现了出来

在这里插入图片描述

这样,我们创建的控制器的文档就这样显示出来了,并且我们可以直接在该页面使用我们的控制器进行各种测试。十分方便。

这篇关于不用在写这么多的接口文档-SpringBoot整合Swagger,解放你打接口文档的双手的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!



http://www.chinasem.cn/article/779310

相关文章

JVM 的类初始化机制

前言 当你在 Java 程序中new对象时,有没有考虑过 JVM 是如何把静态的字节码(byte code)转化为运行时对象的呢,这个问题看似简单,但清楚的同学相信也不会太多,这篇文章首先介绍 JVM 类初始化的机制,然后给出几个易出错的实例来分析,帮助大家更好理解这个知识点。 JVM 将字节码转化为运行时对象分为三个阶段,分别是:loading 、Linking、initialization

Spring Security 基于表达式的权限控制

前言 spring security 3.0已经可以使用spring el表达式来控制授权,允许在表达式中使用复杂的布尔逻辑来控制访问的权限。 常见的表达式 Spring Security可用表达式对象的基类是SecurityExpressionRoot。 表达式描述hasRole([role])用户拥有制定的角色时返回true (Spring security默认会带有ROLE_前缀),去

浅析Spring Security认证过程

类图 为了方便理解Spring Security认证流程,特意画了如下的类图,包含相关的核心认证类 概述 核心验证器 AuthenticationManager 该对象提供了认证方法的入口,接收一个Authentiaton对象作为参数; public interface AuthenticationManager {Authentication authenticate(Authenti

Spring Security--Architecture Overview

1 核心组件 这一节主要介绍一些在Spring Security中常见且核心的Java类,它们之间的依赖,构建起了整个框架。想要理解整个架构,最起码得对这些类眼熟。 1.1 SecurityContextHolder SecurityContextHolder用于存储安全上下文(security context)的信息。当前操作的用户是谁,该用户是否已经被认证,他拥有哪些角色权限…这些都被保

Spring Security基于数据库验证流程详解

Spring Security 校验流程图 相关解释说明(认真看哦) AbstractAuthenticationProcessingFilter 抽象类 /*** 调用 #requiresAuthentication(HttpServletRequest, HttpServletResponse) 决定是否需要进行验证操作。* 如果需要验证,则会调用 #attemptAuthentica

Spring Security 从入门到进阶系列教程

Spring Security 入门系列 《保护 Web 应用的安全》 《Spring-Security-入门(一):登录与退出》 《Spring-Security-入门(二):基于数据库验证》 《Spring-Security-入门(三):密码加密》 《Spring-Security-入门(四):自定义-Filter》 《Spring-Security-入门(五):在 Sprin

Java架构师知识体认识

源码分析 常用设计模式 Proxy代理模式Factory工厂模式Singleton单例模式Delegate委派模式Strategy策略模式Prototype原型模式Template模板模式 Spring5 beans 接口实例化代理Bean操作 Context Ioc容器设计原理及高级特性Aop设计原理Factorybean与Beanfactory Transaction 声明式事物

Java进阶13讲__第12讲_1/2

多线程、线程池 1.  线程概念 1.1  什么是线程 1.2  线程的好处 2.   创建线程的三种方式 注意事项 2.1  继承Thread类 2.1.1 认识  2.1.2  编码实现  package cn.hdc.oop10.Thread;import org.slf4j.Logger;import org.slf4j.LoggerFactory

JAVA智听未来一站式有声阅读平台听书系统小程序源码

智听未来,一站式有声阅读平台听书系统 🌟&nbsp;开篇:遇见未来,从“智听”开始 在这个快节奏的时代,你是否渴望在忙碌的间隙,找到一片属于自己的宁静角落?是否梦想着能随时随地,沉浸在知识的海洋,或是故事的奇幻世界里?今天,就让我带你一起探索“智听未来”——这一站式有声阅读平台听书系统,它正悄悄改变着我们的阅读方式,让未来触手可及! 📚&nbsp;第一站:海量资源,应有尽有 走进“智听

活用c4d官方开发文档查询代码

当你问AI助手比如豆包,如何用python禁止掉xpresso标签时候,它会提示到 这时候要用到两个东西。https://developers.maxon.net/论坛搜索和开发文档 比如这里我就在官方找到正确的id描述 然后我就把参数标签换过来