【swagger】1.swagger提供开发者文档--简单集成到spring boot中【spring mvc】【spring boot】

2022-12-08 13:32:22

swagger提供开发者文档

========================================================

作用：想使用swagger的同学，一定是想用它来做前后台分离，后台开发为前台提供API，以供前台的同学调用和调试。

那么swagger的作用就是上面这句话。

具体swagger包含了哪些，swagger官网展示的很齐全

本篇只表达swagger2+spring boot怎么用，也是给想用swagger但是无从下手的同学们带带路！！！！

========================================================

本篇需要准备的东西：

InterllJ Idea/JDK1.8/spring boot 项目一个

========================================================

在这开始之前，你要自己去搭建一个spring boot项目，至于使用maven管理架包或者gradle管理架包，看你自己。

参考地址：

http://www.cnblogs.com/sxdcgaq8080/p/7712874.html. maven+spring boot

http://www.cnblogs.com/sxdcgaq8080/p/8717914.html gradle+spring boot

1.添加依赖

gradle添加依赖

// https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui

    compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.8.0'

    // https://mvnrepository.com/artifact/io.springfox/springfox-swagger2

    compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.8.0'

maven添加依赖

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger2</artifactId>

    <version>2.8.0</version>

</dependency>

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger-ui</artifactId>

    <version>2.8.0</version>

</dependency>

2.swagger配置类

其实这个配置类，只要了解具体能配置哪些东西就好了，毕竟这个东西配置一次之后就不用再动了。

【注意1】：特别要注意的是里面配置了api文件也就是controller包的路径，你要生成API接口文档的controller文件都是放在这个包路径下的，不然生成的文档扫描不到接口。

【注意2】：这个swagger配置类，是要放在你Application类同级，也就是Springboot项目的启动类的同级

package com.sxd.sweeping;

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 Swagger2 {

    @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())

                .select()

                .apis(RequestHandlerSelectors.basePackage("com.sxd.sweeping.controller"))

                .paths(PathSelectors.any())

                .build();

    }

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()

                .title("Spring Boot中使用Swagger2构建RESTful APIs")

                .description("更多精彩博客请关注：http://www.cnblogs.com/sxdcgaq8080/")

                .termsOfServiceUrl("http://www.cnblogs.com/sxdcgaq8080/")

                .contact("Angel挤一挤")

                .version("1.0")

                .build();

    }

}

3.然后就是最简单的controller的swagger的表达了

【注意1】：@ApiImplicitParam 和 @ApiParam 方式均能指定参数规则。

【注意2】：使用@ApiImplicitParam的时候，需要指定paramType。

package com.sxd.sweeping.controller;

import com.sxd.sweeping.entity.User;

import com.sxd.sweeping.repository.UserRepository;

import com.sxd.sweeping.response.GenericResponse;

import io.swagger.annotations.Api;

import io.swagger.annotations.ApiImplicitParam;

import io.swagger.annotations.ApiImplicitParams;

import io.swagger.annotations.ApiOperation;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.web.bind.annotation.*;

import java.sql.Date;

import java.util.UUID;

@Api(value = "userController",description = "用户相关操作",tags = {"用户"})

@RestController

@RequestMapping("users")

public class UserController {

    @Autowired

    private UserRepository userRepository;

    @ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户的详细信息")

    @ApiImplicitParam(name = "id", value = "用户ID", required = true,dataType = "Long",paramType = "path")

//    @RequestMapping(value = "/{id}",method = RequestMethod.GET)

    @GetMapping(value = "/{id}")

    public GenericResponse<User> get(@PathVariable Long id){

        User user = userRepository.findUserById(id);

        GenericResponse<User> genericResponse = new GenericResponse<>();

        genericResponse.setItems(user);

        genericResponse.setCode(200);

        if(user != null){

            genericResponse.setMessage("查询成功");

        }else{

            genericResponse.setMessage("暂无此人");

        }

        return  genericResponse;

    }

    @ApiOperation(value = "增加用户", notes = "根据user对象创建用户")

    @ApiImplicitParam(name = "user", value = "用户详细信息User", required = true,dataType = "User")

//    @RequestMapping(method = RequestMethod.POST)

    @PostMapping()

    public GenericResponse<User> add(@RequestBody User user){

        String password = UUID.randomUUID().toString();

        user.setPassword(password);

        user =  userRepository.save(user);

        GenericResponse<User> genericResponse = new GenericResponse<>();

        genericResponse.setItems(user);

        genericResponse.setCode(200);

        if(user != null){

            genericResponse.setMessage("新增成功");

        }else{

            genericResponse.setMessage("新增失败");

        }

        return  genericResponse;

    }

    @ApiOperation(value = "删除用户", notes = "根据url的id来删除用户")

    @ApiImplicitParam(name = "id", value = "用户ID", required = true,dataType = "Long",paramType = "path")

//    @RequestMapping(value = "/{id}",method = RequestMethod.DELETE)

    @DeleteMapping(value = "/{id}")

    @ResponseBody

    public GenericResponse<User> delete(@PathVariable Long id){

        userRepository.deleteById(id);

        GenericResponse<User> genericResponse = new GenericResponse<>();

        genericResponse.setCode(200);

        genericResponse.setMessage("删除成功");

        return genericResponse;

    }

    @ApiOperation(value = "更新用户", notes = "根据url的id来更新用户信息")

    @ApiImplicitParams({

            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path"),

            @ApiImplicitParam(name = "user", value = "用户实体user", required = true,dataType = "User")

    })

//    @RequestMapping(value = "/{id}",method = RequestMethod.PUT)

    @PutMapping(value = "/{id}")

    public GenericResponse<User> update(@PathVariable Long id, @RequestBody  User user){

        User user1 = userRepository.findUserById(id);

        user1.setGender(user.getGender());

        user1.setMobile(user.getMobile());

        user1.setRealname(user.getRealname());

        user1.setUpdateAt(new Date(System.currentTimeMillis()));

        GenericResponse<User> genericResponse = new GenericResponse<>();

        genericResponse.setCode(200);

        genericResponse.setMessage("更新成功");

        genericResponse.setItems(userRepository.saveAndFlush(user1));

        return genericResponse;

    }

    @ApiOperation(value = "更新用户局部信息", notes = "根据url的id来更新用户局部信息")

    @ApiImplicitParams({

            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path"),

            @ApiImplicitParam(name = "realname", value = "用户名", required = true,dataType = "String"),

            @ApiImplicitParam(name = "mobile", value = "联系方式", required = true,dataType = "String")

    })

//    @RequestMapping(value = "/{id}",method = RequestMethod.PATCH)

    @PatchMapping(value = "/{id}")

    public GenericResponse<User> patch(@PathVariable Long id, String realname, String mobile){

        User user = userRepository.findUserById(id);

        user.setRealname(realname);

        user.setMobile(mobile);

        GenericResponse<User> genericResponse = new GenericResponse<>();

        genericResponse.setCode(200);

        genericResponse.setMessage("更新成功");

        genericResponse.setItems(userRepository.saveAndFlush(user));

        return genericResponse;

    }

}

4.项目启动后，就可以访问地址：

http://localhost:8080/swagger-ui.html#

访问你的api接口了。

展示API页面如下：

==============================================================================

常用注解详情：

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：作用在controller类上，修饰整个类，描述Controller的作用

@ApiOperation：作用在controller类的方法上，描述一个类的一个方法，或者说一个接口的功能

@ApiParam：单个参数描述

@ApiModel：用在返回对象类上，用对象来接收参数
@ApiModelProperty：用在参数对象的字段上

@ApiProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：用在@ApiResponses里面，HTTP响应其中1个描述

@ApiResponses：用在controller方法上，HTTP响应整体描述

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiImplicitParam：用在@ApiImplicitParams中，一个请求参数

@ApiImplicitParams：用在controller方法上，多个请求参数

各个注解中属性值的解析：

@ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的各个方面

paramType：参数放在哪个地方 
· header --> 请求参数的获取：@RequestHeader 
· query -->请求参数的获取：@RequestParam 
· path（用于restful接口）--> 请求参数的获取：@PathVariable 
· body（不常用） 
· form（不常用） 
name：参数名 
dataType：参数类型 
required：参数是否必须传 
value：参数的意思 
defaultValue：参数的默认值

@Api：作用在controller类上，修饰整个类，描述Controller的作用

属性名称    备注

value    url的路径值

tags    如果设置这个值、value的值会被覆盖

description    对api资源的描述

basePath    基本路径可以不配置

position    如果配置多个Api 想改变显示的顺序位置

produces    For example, "application/json, application/xml"

consumes    For example, "application/json, application/xml"

protocols    Possible values: http, https, ws, wss.

authorizations    高级特性认证时配置

hidden    配置为true 将在文档中隐藏

@ApiOperation：作用在controller类的方法上，描述一个类的一个方法，或者说一个接口的功能

属性名称    备注

value    url的路径值

tags    如果设置这个值、value的值会被覆盖

description    对api资源的描述

basePath    基本路径可以不配置

position    如果配置多个Api 想改变显示的顺序位置

produces    For example, "application/json, application/xml"

consumes    For example, "application/json, application/xml"

protocols    Possible values: http, https, ws, wss.

authorizations    高级特性认证时配置

hidden    配置为true 将在文档中隐藏

response    返回的对象

responseContainer    这些对象是有效的 "List", "Set" or "Map".，其他无效

httpMethod    "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"

code    http的状态码 默认

extensions    扩展属性

@ApiParam：单个参数描述

示例：

public UniVerResponse<HuaYangArea> huayang(@ApiParam(value = "create a entity  HuaYangArea") @RequestBody HuaYangArea huaYangArea)

属性名称    备注

name    属性名称

value    属性值

defaultValue    默认属性值

allowableValues    可以不配置

required    是否属性必填

access    不过多描述

allowMultiple    默认为false

hidden    隐藏该属性

example    举例子

@ApiResponse：用在@ApiResponses里面，HTTP响应其中1个描述

示例：

@ApiOperation(value = "保存HUAYANG信息",notes = "传入HUAYANG实体，保存HUAYANG信息")

    @PostMapping()

    @ApiResponses({

            @ApiResponse(code = ,message = "success"),

            @ApiResponse(code = ,message = "参数错误"),

            @ApiResponse(code = ,message = "业务错误"),

            @ApiResponse(code = ,message = "系统异常")})

    public UniVerResponse<HuaYangArea> huayang(@ApiParam(value = "create a entity  HuaYangArea") @RequestBody HuaYangArea huaYangArea){

属性名称    备注

code    http的状态码

message    描述

response    默认响应类 Void

reference    参考ApiOperation中配置

responseHeaders    参考 ResponseHeader 属性配置说明

responseContainer    参考ApiOperation中配置

==========================================================================

Get等价：

@RequestMapping(value = "/{id}",method = RequestMethod.GET)

等价于：@GetMapping(value = "/{id}")

Post等价：【创建资源】

@RequestMapping(method = RequestMethod.POST)

等价于：@PostMapping()

Delete等价：

@RequestMapping(value = "/{id}",method = RequestMethod.DELETE)

等价于：@DeleteMapping(value = "/{id}")

Put等价：【更新已存在的资源，完全替换，所以接收到的是id和完整的对象，在处理上如果对象中有未给值的字段，则更新数据库中字段值替换为空】

@RequestMapping(value = "/{id}",method = RequestMethod.PUT)

等价于：@PutMapping(value = "/{id}")

Patch等价：【更新已经存在资源的部分字段，局部更新，仅提供id和要更新的字段，在处理上仅更新要更新的字段，其他字段不变】

@RequestMapping(value = "/{id}",method = RequestMethod.PATCH)

等价于：@PatchMapping(value = "/{id}")

===========================================================================

【注意】：

因为返回的都是统一处理响应格式，所以每个API接口上都要加上@ResponseBody注解。

所以，可以选择在Controller上加上@RestController=@Controller+@ResponseBody

===========================================================================

下一篇地址：

http://www.cnblogs.com/sxdcgaq8080/p/8797318.html

码农公寓

【注意1】：@ApiImplicitParam 和 @ApiParam 方式均能指定参数规则。

【注意2】：使用@ApiImplicitParam的时候，需要指定paramType。

相关文章