当前位置：首页 > 编程日记 > 正文

MP实战系列(二)之集成swagger

编程日记 2024-09-14 19:30:00

其实与spring+springmvc+mybatis集成swagger没什么区别，只是之前写的太不好了，所以这次决定详细写。

提到swagger不得不提rest,rest是一种架构风格，里面有对不同的资源有不同的请求标识。例如PUT,POST,GET,DELETE，OPTIONS,HEAD,PATCH等。

对于技术的初学，最好的话还是建议去官网，官网最详细也最权威，虽然不少博客对此有挺好的解说，但还是强烈建议去官网，不要求仔仔细细阅读，至少读个大概。

对于目前，有人要问我swagger能做什么，可以解决什么问题？我不能详细的给你一一道来，因为我对此不是十分精通，至少它解决了我两个问题，第一个，接口文档的编写，之前通过接口文档，但是随着后续接口是越来越多，文档也需要变来变去，本来就力不从心，又是一大堆接口要写，又是文档要写，swagger就可以轻松的解决这个问题，通过swagger注解可以让安卓方面清楚看到这个接口的作用是什么，还可以在线测试，返回数据；第二个问题，就是接口管理，通过swagger我可以根据接口类型，比如有用户管理，文章管理等等，我通过swagger注解可以轻松的给它们分累以方便我下次编写或修改。

pom依赖:

    <!-- swagger -->  <dependency>    <groupId>com.mangofactory</groupId>    <artifactId>swagger-springmvc</artifactId> <version>1.0.2</version>    </dependency>

就是上述这一个，我的MP实战系列（一）中pom就有这个。

要集成swagger导入上述的依赖之外，还要添加一个类并在springmvc.xml中配置

    <!-- 将 springSwaggerConfig加载到spring容器 -->  <bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />  <!-- 将自定义的swagger配置类加载到spring容器 -->  <bean class="com.lms.swagger.SwaggerConfig" />

SwaggerConfig.java

package com.lms.swagger;import org.springframework.beans.factory.annotation.Autowired;  
import org.springframework.context.annotation.Bean;  import com.mangofactory.swagger.configuration.SpringSwaggerConfig;  
import com.mangofactory.swagger.models.dto.ApiInfo;  
import com.mangofactory.swagger.plugin.EnableSwagger;  
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;  @EnableSwagger  
public class SwaggerConfig {  private SpringSwaggerConfig springSwaggerConfig;  /** * Required to autowire SpringSwaggerConfig */  @Autowired  public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig)  {  this.springSwaggerConfig = springSwaggerConfig;  }  /** * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc * framework - allowing for multiple swagger groups i.e. same code base * multiple swagger resource listings. */  @Bean  public SwaggerSpringMvcPlugin customImplementation()  {  return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)  .apiInfo(apiInfo())  .includePatterns(".*?");  }  private ApiInfo apiInfo()  {  ApiInfo apiInfo = new ApiInfo(  "springmvc搭建swagger",  "spring-API swagger测试",  "My Apps API terms of service",  "19****81**@qq.com",  "web app",  "My Apps API License URL");  return apiInfo;  }  
}

上述的步骤可以解说为：导入swagger-springmvc依赖并在springmvc.xml中配置，编写对应的配置类，就算完成springmvc集成swagger的第一大步了，当然这还远远不够，还需要导入一个很重要的那就是swagger相关的类库(js,css等之类的)

可从github上下载:https://github.com/swagger-api/swagger-ui

本人使用的是2.2.10版本

下载完成后，进行解压，解压后的目录为:

将红色标记处的dist文件夹里面的js,css之类的全部导入webapp目录下

dist目录图为:

index.html中有一处地址需要修改

将此处的url替换为自己本地项目地址，例如http://localhost:8080/blog/api-docs

然后在对应的Controller添加如下注解，此处以我博客系统的UserController作为演示示例:

package com.blog.controller;import java.util.HashMap;
import java.util.Map;import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;import com.alibaba.fastjson.JSON;
import com.baomidou.mybatisplus.mapper.EntityWrapper;
import com.blog.entity.UserEntity;
import com.blog.service.UserService;
import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiImplicitParam;
import com.wordnik.swagger.annotations.ApiImplicitParams;
import com.wordnik.swagger.annotations.ApiOperation;
import com.wordnik.swagger.annotations.ApiParam;/*** ** @author youcong* @email ${email}* @date 2018-04-21 15:27:01*/
@Api(value="博客用户管理")
@RestController
@RequestMapping("user")
public class UserController {@Autowired private UserService userService;  @ApiOperation(value = "获得用户列表", notes = "列表信息", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)@PostMapping(value="/getById")public String list(@ApiParam(value = "用户ID", required = true) @RequestParam Integer id) {EntityWrapper<UserEntity> wrapper = new EntityWrapper<UserEntity>();wrapper.eq("user_id", id);UserEntity userEntity = userService.selectOne(wrapper);return JSON.toJSONString(userEntity);}}

效果图如下:

可在线进行接口测试，对于后台开发者来说，之前没有使用swagger通常使用postMan测试post请求，现在使用了swagger方便管理接口，又可以在线测试。

swagger常用注解:

最常用的5个注解

（1）@Api：修饰整个类，描述Controller的作用

（2）@ApiOperation：描述一个类的一个方法，或者说一个接口

（3）@ApiParam：单个参数描述

@ApiModel：：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候；

@ApiProperty：描述一个model的属性。

其他注解:

@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
- paramType：参数放在哪个地方
  - header-->请求参数的获取：@RequestHeader
  - query-->请求参数的获取：@RequestParam
  - path（用于restful接口）-->请求参数的获取：@PathVariable
  - body（不常用）
  - form（不常用）
- name：参数名
- dataType：参数类型
- required：参数是否必须传
- value：参数的意思
- defaultValue：参数的默认值
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
- code：数字，例如400
- message：信息，例如"请求参数没填好"
- response：抛出异常的类

更详细的可参考此网址:https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel

许多注解多用用自然知道，熟能生巧。

https://www.dkcj.cn/info/18730.html

MP实战系列(二)之集成swagger

相关文章：

Task04：青少年软件编程（Python）等级考试模拟卷（一级）

Python 解决一行代码分成多行及多行代码放在一行

Task05：青少年软件编程（Python）等级考试模拟卷（一级）

控件的实际大小与呈现大小

MXNet动手学深度学习笔记：卷积计算

Python求100以内的素数和并输出

Android KTV

毛慧昀：决策树实现对鸢尾花数据集的分类

golang strings.Fields 使用

Python 用户的三次登录机会

Realm_King 之 .NET操作XML完整类

全网把Map中的hash()分析的最透彻的文章，别无二家。

电子学会青少年编程等级考试Python一级题目解析03

Python 函数知识汇总

Android四大基本组件介绍与生命周期

【快速入门系列】简述 for...in 和 for...of 区别

【新周报（050）】Datawhale组队学习

PyInstaller库的使用

myeclipse 遇到的一些问题及解决方案

电子学会青少年编程等级考试案例：曲奇饼干

linux下tar.gz、tar、bz2、zip等解压缩、压缩命令小结

Python组合数据类型之集合类型

MVC系列1-MVC基础

洛谷 P1816 忠诚

电子学会青少年编程等级考试Python案例08

Python组合数据类型之序列类型

hdu-3071 Gcd Lcm game---质因数分解+状态压缩+线段树

一个比较保守的404页面

【组队学习】【34期】组队学习内容详情

Python组合数据类型之字典类型