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

其实与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.cnblogs.com/youcong/p/9011302.html

时间: 2024-11-05 16:39:47

MP实战系列(二)之集成swagger的相关文章

MP实战系列(七)之集成springboot

springboot是现在比较流行的微服使用的框架,springboot本质上就是将spring+springmvc+mybatis零配置化,基本上springboot的默认配置符合我们的开发.当然有一部分还是需要自定义的. 本章不是专门讲springboot的,主要将springboot+mybatis plus是如何整合的. 一.导入pom依赖 <parent> <groupId>org.springframework.boot</groupId> <arti

MP实战系列(九)之集成Shiro

下面示例是在之前的基础上进行的,大家如果有什么不明白的可以参考MP实战系列的前八章 当然,同时也可以参考MyBatis Plus官方教程 建议如果参考如下教程,使用的技术为spring+mybatis plus + springmvc+jdk8+maven工程 满足这个条件可以减少不必要的麻烦,当然持久层也可以用mybatis. 只要按照如下示例来,也不会有大问题的.之前我也强调过mybatis和mybatis plus的区别主要是封装和继承,mybatis plus封装一系列增删改查的方法,但

MP实战系列(十二)之封装方法详解(续二)

继续MP实战系列(十一)之封装方法详解(续一)这篇文章之后. 此次要讲的是关于查询. 查询是用的比较多的,查询很重要,好的查询,加上索引如鱼得水,不好的查询加再多索引也是无济于事. 1.selectById()方法 演示示例: UserEntity user = ud.selectById(33); System.out.println(user.getEmail()); 简单的说明: 如果是在MyBatis中,需要再对应的xml编写这样的sql select column1,column2..

[CXF REST标准实战系列] 二、Spring4.0 整合 CXF3.0,实现测试接口(转)

转自:[CXF REST标准实战系列] 二.Spring4.0 整合 CXF3.0,实现测试接口 文章Points: 1.介绍RESTful架构风格 2.Spring配置CXF 3.三层初设计,实现WebService接口层 4.撰写HTTPClient 客户端,并实现简单调用 介绍RESTful架构风格 REST是REST之父Roy Thomas创造的,当时提出来了REST的6个特点:客户端-服务器的.无状态的.可缓存的.统一接口.分层系统和按需编码.其具有跨语言和跨平台的优势. REST是一

ASP.Net Core2.1中的HttpClientFactory系列二:集成Polly处理瞬态故障

前言:最近,同事在工作中遇到了使用HttpClient,有些请求超时的问题,辅导员让我下去调研一下,HttpClinet的使用方式已经改成了之前博客中提到的方式,问题的原因我已经找到了,就是因为使用了伪异步,导致阻塞主线程.在之前的博客中有园友,建议在使用静态的HttpClinet时务必使用它的Async方法,所以就得从头到尾异步化.这一点在之前的文章中没有提,这里作为补充,也感谢这位园友.关于怎么使用异步编程,在这里我就不聊了,大家可以看看其他的博客,看完公司的代码之后,我想强调的是,在使用异

SQL Server 性能优化实战系列(二)

SQL Server datetime数据类型设计.优化误区 一.场景 在SQL Server 2005中,有一个表TestDatetime,其中Dates这个字段的数据类型是datetime,如果你看到表的记录如下图所示,你最先想到的是什么呢? (图1:数据列表) 你看到这些数据,是不是觉得这样的设计既浪费了存储空间,又使得这个列的索引增大,查询起来更慢,你也想使用一些其它的数据类型来代替这个datetime吧? 其实大家都是这么想的,这个方向是100%正确的,但是在写这篇文章以前,我进入了两

MP实战系列(三)之实体类讲解

首先说一句,mybatis plus实在太好用了! mybaits plus的实体类: 以我博客的用户类作为讲解 package com.blog.entity; import com.baomidou.mybatisplus.annotations.TableField; import com.baomidou.mybatisplus.annotations.TableId; import com.baomidou.mybatisplus.annotations.TableLogic; imp

SpringBoot系列五:集成Swagger文档

本篇开始介绍Api文档Swagger的集成 一.引入maven依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfo

MP实战系列(四)之DAO讲解

说到DAO不得不提一个开发名词"三层架构",所谓的三层架构是什么呢?简单的可以概括为数据访问层,业务逻辑层,界面层(又称表现层). 这也是我们Java开发常用的手段,经常有人将三层架构和mvc模式混淆,在我看来,三层架构就是三层架构,mvc只是三层架构中的表现层中的架构,相当于在一个比较大的层面,往里面在细分,mvc细分,可分为模型,视图,控制器,在这里模型通常指数据,也可以叫JavaBean,而视图的话,这个视图就是展示给用户看的,通常用于视图的模板可以为jsp,freemarker