springboot学习笔记（十一）—— springboot使用swagger2构建Restful API

最新推荐文章于 2024-01-15 11:31:10 发布

LuckyToMeet-Dian叶

最新推荐文章于 2024-01-15 11:31:10 发布

阅读量660

点赞数

分类专栏： springboot入门系列 springboot学习笔记

本文链接：https://blog.csdn.net/weixin_41622183/article/details/84205566

版权

springboot入门系列同时被 2 个专栏收录

11 篇文章 0 订阅

订阅专栏

springboot学习笔记

11 篇文章 0 订阅

订阅专栏

前言：

快~快~快元旦咯，一年又过去了，似乎这两三个月都不怎么写博客了。今天先补一篇，后面找假期把最近这段时间的东西都整合起来吧~来场大爆发！

废话不说了，今天来学习一下springboot使用swagger2构建Restful API学习，学习一下如何使用swagger来构建自己的API文档。

准备工作：先加入maven依赖

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

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.8.0</version>
</dependency>

直接上代码：

一、首先要写一个配置文件，如下：

注意：该配置文件放置位置一定要和启动类在同一目录下，如图：

package com.wen.gentle;



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.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

/**
 * @author Gentle
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
//swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
    @Bean
    public Docket createRestApi() {
        List<Parameter> pars = new ArrayList<Parameter>();

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .globalOperationParameters(pars)
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.wen.gentle"))
                .paths(PathSelectors.any())
                .build();
    }
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot 测试使用 Swagger2 构建RESTful API")
                //创建人
                .contact(new Contact("Gentle", "localhost:8080", "hh@qq.com"))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
 
 
}

二、开始构建我们的文档啦

package com.wen.gentle.controller;

import com.wen.gentle.vo.Users;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;

/**
 * @Description:
 * @Author: Gentle
 * @date 2018/12/29 10:25
 */
@RestController
@Api(tags="用户管理",description = "这是一个用户的控制器")
public class UserController {
    @ApiOperation(value = "用户管理",notes = "用户操作",httpMethod ="POST")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name" ,value = "用户名字",required = true,dataType = "String"),
            @ApiImplicitParam(name = "age" ,value = "用户年龄",dataType = "int",required = true),
            @ApiImplicitParam(name = "time" ,value = "用户时间",required = true,dataType = "date"),
    })
    //api返回的东西
    @ApiResponses({
            //返回的东西，有返回码和信息，可以自定义
            @ApiResponse(code = 200,message = "success",response = Users.class),
            @ApiResponse(code = 403,message = "不支持的请求"),
            @ApiResponse(code = 404,message = "找不到资源"),
            //自定义返回码
            @ApiResponse(code = -99,message = "未知异常",response = Exception.class),

    })
    @PostMapping(value = "getUsersInfo")
    public Users getUsersInfo(Users users) {
        //将信息直接返回
        return users;
    }

    @ApiIgnore  //这个注解标志不用显示出来
    @PostMapping(value = "test")
    public String query(){


        return "该方法不显示";
    }



}

model类：

package com.wen.gentle.vo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.util.Date;

/**
 * @Description:
 * @Author: Gentle
 * @date 2018/12/29 10:26
 */
@ApiModel(value="users", description="用户对象")
@Data
public class Users {
    @ApiModelProperty(value="用户名字",dataType = "String" ,name = "name",example = "Gentle")
    private String name;
    @ApiModelProperty(value = "用户年龄",dataType = "int",name = "age",example = "100")
    private Integer age;
    @ApiModelProperty(value = "时间",dataType = "date",name = "time",example = "2018-12-29")
    private Date time;

}

三、注解释义。

这一步可以先不了解，先去第四步实现出来再回来学习。

这时候要说说注解的作用了（附图演示）

首先说说这个@Api()

例子：@Api(tags="用户管理",description = "这是一个用户的控制器") 告诉说这是一个swagger资源啦。

targs属性的意思是展示这个类的标题

description属性是描述这个类是做什么的

如下图：

注解：@ApiOperation(）

例子：@ApiOperation(value = "用户管理",notes = "用户操作")

value属性：是意思可以理解为描述这个接口的作用

notes属性：简单说理解为注释吧，笔记也可以，不知道怎么解释

如图：

注解：@ApiImplicitParams(）这个意思是多个请求参数，就是包含下面的@ApiImplicitParam(）注解。

@ApiImplicitParam(）一个请求参数

例子：

@ApiImplicitParams({
        @ApiImplicitParam(name = "name" ,value = "用户名字",required = true,dataType = "String"),
        @ApiImplicitParam(name = "age" ,value = "用户年龄",dataType = "int",required = true),
        @ApiImplicitParam(name = "time" ,value = "用户时间",required = true,dataType = "date"),
})

常用属性：

name属性：请求参数的名字

value属性：标识请求参数是什么意思

requird属性：是否一定需要这个参数，默认为false

dataType属性：请求参数的数据类型。注意没有写Integer类型的话，在展示会显示引用类型，正确直接写int就好

例图：

注解： @ApiResponses({}) api返回多种类型数据

@ApiResponse(）返回的具体数据，可以是List，String等数据类型，状态码，信息等

例子：

@ApiResponses({
        //返回的东西，有返回码和信息，可以自定义
        @ApiResponse(code = 200,message = "success",response = Users.class),
        @ApiResponse(code = 403,message = "不支持的请求"),
        @ApiResponse(code = 404,message = "找不到资源"),
        //自定义返回码
        @ApiResponse(code = -99,message = "未知异常",response = Exception.class),
})

常用属性：

code属性：状态码，可以常用的200,302,403,502等，也可以自定义

message属性：返回错误信息，或者正确信息

response属性：返回的对象，指定返回的对象。

例图：