Day 32 springboot基础10 集成swagger2

Swagger

• 编写和维护接口文档是每个程序员的职责，根据 Swagger2 可以快速帮助我们编写最新的API接口文档，再也不用担心开会前仍忙于整理各种资料了，间接提升了团队开发的沟通效率。常用注解swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

• Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

• 作用：

  1. 接口的文档在线自动生成。
  2. 功能测试。

实现步骤

1、添加jar包

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

2、配置类

Swagger2 配置类

• @Configuration 让 Spring 容器加载该配置类
• @EnableSwagger2 用于启动 swagger2

Swagger2 启动后

• 通过 buildDocket 函数创建Docket的Bean
• buildApiInfo() 用来创建该Api的基本信息（这些基本信息会展现在文档页面中）
• apiInfo() 用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。
• select() 函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，
  一般采用指定扫描的包路径来定义
• Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。
• RequestHandlerSelectors.basePackage(“com.zz.controller”) 为 Controller 包路径，不然生成的文档扫描不到接口

package com.zz.config;

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

@Configuration
@EnableSwagger2
public class SweggerConfig {
    @Bean
    //创建API应用
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(buildApiInf())//----------apiInfo() 增加API相关信息
            .select()
            // 指定controller存放的目录路径
            .apis(RequestHandlerSelectors.basePackage("com.zz.controller"))//扫描文档
            .paths(PathSelectors.any())
            .build();
    }
    
    //创建该API的基本信息（这些基本信息会展现在文档页面中）   访问地址：http://项目实际地址/swagger-ui.ht
    private ApiInfo buildApiInf() {
        return new ApiInfoBuilder()
            .title("系统RESTful API文档")//-------------大标题
             .description("EHR Platform's REST API, all the applications could access the Object model data via JSON.")//---详细描述
            .contact(new Contact("Bsea", "https://me.csdn.net/h356363", "yinyouhai@aliyun.com"))//-----------作者
            .version("1.0")//--------------版本
            .build();
    }
}
-----------------------------------------------------------------------------------------------------------------
 private ApiInfo testApiInfo() {
        return new ApiInfoBuilder()
            .title("Electronic Health Record(EHR) Platform API")//大标题
           
            .version("1.0")//版本
            .termsOfServiceUrl("NO terms of service")
            .contact(new Contact("小单", "http://blog.csdn.net/catoop", "365384722@qq.com"))//作者
            .license("The Apache License, Version 2.0")
            .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
            .build();
    }

设置	说明
Version	API版本号
Title	设置文档的标题
Description	设置文档的描述
Contact	设置文档的联系方式
TermsOfServiceUrl	服务条款说明地址
license	开源协议
licenseUrl	协议地址

3、Entity

package com.zz.entity;

public class User {
	
	private String id;
	private String name;
	private String pwd;
	private String sex;
	private int age;
	...
	//..get set方法
	}

4、Controller

package com.zz.controller;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;

import com.zz.entity.User;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import springfox.documentation.annotations.ApiIgnore;

@Api(value = "用户Controller")
@Controller
@RequestMapping("user")
public class UserController {

    @ApiIgnore
    @GetMapping("hello")
    public @ResponseBody String hello() {
        return "hello";
    }
    //查询
    @ApiOperation(value = "获取用户信息", notes = "根据用户id获取用户信息")
    @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long", paramType = "path")
    @GetMapping("/{id}")
    public @ResponseBody User getUserById(@PathVariable(value = "id") String id) {
        User user = new User();
        user.setId(id);
        user.setName("mrbird");
        user.setAge(25);
        return user;
    }

    @ApiOperation(value = "获取用户列表", notes = "获取用户列表")
    @GetMapping("/list")
    public @ResponseBody List<User> getUserList() {
        List<User> list = new ArrayList<>();
        User user1 = new User();
        user1.setId("1l");
        user1.setName("mrbird");
        user1.setAge(25);
        list.add(user1);
        User user2 = new User();
        user2.setId("2l");
        user2.setName("scott");
        user2.setAge(29);
        list.add(user2);
        return list;
    }
    //增加
    @ApiOperation(value = "新增用户", notes = "根据用户实体创建用户")
    @ApiImplicitParam(name = "user", value = "用户实体", required = true, dataType = "User")
    @PostMapping("/add")
    public @ResponseBody Map<String, Object> addUser(@RequestBody User user) {
        Map<String, Object> map = new HashMap<>();
        map.put("result", "success");
        return map;
    }
    //删除
    @ApiOperation(value = "删除用户", notes = "根据用户id删除用户")
    @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long", paramType = "path")
    @DeleteMapping("/{id}")
    public @ResponseBody Map<String, Object> deleteUser(@PathVariable(value = "id") Long id) {
        Map<String, Object> map = new HashMap<>();
        map.put("result", "success");
        return map;
    }
    //修改
    @ApiOperation(value = "更新用户", notes = "根据用户id更新用户")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long", paramType = "path"),
        @ApiImplicitParam(name = "user", value = "用户实体", required = true, dataType = "User") })
    @PutMapping("/{id}")
    public @ResponseBody Map<String, Object> updateUser(@PathVariable(value = "id") Long id, @RequestBody User user) {
        Map<String, Object> map = new HashMap<>();
        map.put("result", "success");
        return map;
    }

}

/**

8**
**/

常用注解

-----详细参考：Swagger2常用注解说明 https://www.520mwx.com/view/63166
-----参考：Swagger2学习笔记 https://blog.csdn.net/SIMBA1949/article/details/80926126 ！！！！！！！
---- swagger2 注解说明 https://blog.csdn.net/xiaojin21cen/article/details/78654652
---- Swagger使用指南 https://blog.csdn.net/sanyaoxu_2/article/details/80555328

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

@Api(value = "用户Controller")
@Controller
@RequestMapping("user")
public class UserController {
		....
}

常用参数	说明
tags=" "	说明该类的作用，非空时将覆盖value的值，可以在UI界面上看到的注解，如果tags多个值，会生成多个list
value=" "	描述类的作用，不会在界面上显示

其他参数	说明
description	对api资源的描述，在1.5版本后不再支持
basePath	基本路径可以不配置，在1.5版本后不再支持
position	如果配置多个Api 想改变显示的顺序位置，在1.5版本后不再支持
produces	设置MIME类型列表（output），例：“application/json, application/xml”，默认为空
consumes	设置MIME类型列表（input），例：“application/json, application/xml”，默认为空
protocols	设置特定协议，例：http， https， ws， wss。
authorizations	获取授权列表（安全声明），如果未设置，则返回一个空的授权值。
hidden	默认为false， 配置为true 将在文档中隐藏

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

常用参数	说明
value=" "	说明方法的用途、作用,用于方法描述
notes=" "	方法的备注说明、用于提示内容

@ApiParam：单个参数描述

常用参数	说明
name	参数名称，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致
value	参数说明
required	属性是否必填，默认为false [路径参数必须填]
defaultValue	参数默认值

@ApiModel：用对象来接收参数

• 用在请求的类上，表示对类的说明

• 用于响应类上，表示一个返回响应数据的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）

常用参数	说明
description	对对象的描述
value	表示对象名

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

• @ApiModelProperty：用在属性上，描述响应类的属性
  • value：字段说明
  • name：重写属性名
  • dataType：重写属性类型
  • example：举例说明
  • hidden：隐藏

@ApiResponses：HTTP响应整体描述

用在请求的方法上，表示一组响应

• code：数字，例如400
• message：信息，例如"请求参数没填好"
• response：抛出异常的类

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

@ApiResponse：HTTP响应其中1个描述

@ResponseBody
@PostMapping(value="/update/{id}")
@ApiOperation(value = "修改用户信息",notes = "打开页面并修改指定用户信息")
@ApiResponses({
    @ApiResponse(code=400,message="请求参数没填好"),
    @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})
public JsonResult update(@PathVariable String id, UserModel model){}

@ApiIgnore：使用该注解忽略这个API，用于类或者方法上

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

@ApiImplicitParams：多个请求参数，包含多个 @ApiImplicitParam，用于方法上

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

@ApiImplicitParam：一个请求参数，用于方法上

• name：参数名，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致
• value：参数说明
• dataType：参数类型，默认String，其他值dataType=“Integer”
• paramType：参数放在哪个地方
  • header：请求参数的获取 @RequestHeader
  • query：请求参数的获取 @RequestParam
  • path：请求参数的获取 @PathVariable
  • body（不常用）
  • form （不常用）
• required：是否必须填写，参数是否必须传[路径参数必填]
• defaultValue：默认值

@ResponseBody
@PostMapping(value="/login")
@ApiOperation(value = "登录检测", notes="根据用户名、密码判断该用户是否存在")
@ApiImplicitParams({
      @ApiImplicitParam(name = "name", value = "用户名", required = false, paramType = "query", dataType = "String"),
      @ApiImplicitParam(name = "pass", value = "密码", required = false, paramType = "query", dataType = "String") 
})
public UserModel login(@RequestParam(value = "name", required = false) String account,
                @RequestParam(value = "pass", required = false) String password){}

编写RESTful API接口

Spring Boot中包含了一些注解，对应于HTTP协议中的方法：

• @GetMapping 对应HTTP中的GET方法；
  • 处理get请求，传统的RequestMapping来编写应该是@RequestMapping(value = “/get/{id}”, method = RequestMethod.GET)
    新方法可以简写为：
    @GetMapping("/get/{id}")
• @PostMapping对应HTTP中的POST方法；
  • 处理get请求，传统的RequestMapping来编写应该是@RequestMapping(value = “/get/{id}”, method = RequestMethod.GET)
    新方法可以简写为：
    @GetMapping("/get/{id}")
• @PutMapping对应HTTP中的PUT方法；
  • 和PostMapping作用等同，都是用来向服务器提交信息。如果是添加信息，倾向于用@PostMapping，如果是更新信息，倾向于用@PutMapping。两者差别不是很明显。
• @DeleteMapping对应HTTP中的DELETE方法；
  • 删除URL映射
• @PatchMapping对应HTTP中的PATCH方法。

get请求特点：
a. 请求参数会添加到请求资源路径的后面，只能添加少量参数（因为请求行只有一行，大约只能存放2K左右的数据）
b. 请求参数会显示在浏览器地址栏，路由器会记录请求地址 （极为的不安全）
c.如果传输中文，必定会乱码（原因：get请求默认编码格式为：IIO-8859-1,后台编码格式一般为：GBK或者UTF-8）
post请求的特点：
a. 请求参数添加到实体内容里面，可以添加大量的参数（也解释了为什么浏览器地址栏不能发送post请求，在地址栏里我们只能填写URL，并不能进入到Http包的实体当中）
b. 相对安全，但是，post请求不会对请求参数进行加密处理（可以使用https协议来保证数据安全）

原文链接：@GetMapping、@PostMapping、@PutMapping、@DeleteMapping、@PatchMapping、@RequestMapping详解 https://blog.csdn.net/java_xdo/article/details/88711192