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

简介: 其实与spring+springmvc+mybatis集成swagger没什么区别,只是之前写的太不好了,所以这次决定详细写。提到swagger不得不提rest,rest是一种架构风格,里面有对不同的资源有不同的请求标识。

其实与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

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

 

目录
相关文章
|
13天前
|
存储 缓存 安全
LLM应用实战:当图谱问答(KBQA)集成大模型(三)
本文主要是针对KBQA方案基于LLM实现存在的问题进行优化,主要涉及到响应时间提升优化以及多轮对话效果优化,提供了具体的优化方案以及相应的prompt。
256 1
|
13天前
|
存储 自然语言处理 C++
LLM应用实战:当KBQA集成LLM(二)
本文主要是针对KBQA方案基于LLM实现存在的问题进行优化,主要涉及到图谱存储至Es,且支持Es的向量检索,还有解决了一部分基于属性值倒查实体的场景,且效果相对提升。
46 1
|
1天前
|
Java
springboot集成swagger2并分组全局设置Authorization
springboot集成swagger2并分组全局设置Authorization
4 0
|
13天前
|
缓存 自然语言处理 知识图谱
LLM应用实战:当KBQA集成LLM
项目是关于一个博物馆知识图谱,上层做KBQA应用。实现要求是将传统KBQA中的部分模块,如NLU、指代消解、实体对齐等任务,完全由LLM实现,本qiang~针对该任务还是灰常感兴趣的,遂开展了项目研发工作
41 0
|
1月前
|
jenkins Java 持续交付
实战指南:运用Jenkins实现Java项目的持续集成与自动化部署
【4月更文挑战第17天】Jenkins是一款强大的开源CI/CD工具,广泛用于Java项目的自动化构建、测试和部署。通过配置Jenkins环境、创建Job、设定构建触发器和步骤,实现持续集成和部署。集成Maven、Git等工具,确保代码质量并加速上线。持续部署阶段,Jenkins可将工件发布至远程服务器或云环境,实现高效、稳定的自动化流程。实践过程中,关注工作流优化、配置备份和服务器状态监控,以提升整体开发效率和软件质量。
|
1月前
|
XML Java API
Spring Boot中使用集成swagger-bootstrap-ui
Spring Boot中使用集成swagger-bootstrap-ui
57 0
|
1月前
|
Java Maven
【SpringBoot专题_02】springboot集成Swagger详细教程
【SpringBoot专题_02】springboot集成Swagger详细教程
38 0
|
1月前
|
Java 关系型数据库 MySQL
Shiro实战+springboot集成
Shiro实战+springboot集成
51 0
|
1月前
|
Java API Spring
【一】springboot整合swagger
【一】springboot整合swagger
47 0