swagger的使用

首先swagger是什么？

Swagger 是一个用于生成、描述和调用 RESTful 接口的 Web 服务。

简单说Swagger 就是将项目中的接口展现在页面上，并且可以进行接口调用和测试的服务。

相比于postman,我们只需要把值填到对应的参数上面去就可以调用接口,降低调式成本。

首先还是maven坐标：

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

之后还有进行配置：

package com.xiaoteng.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;

/**
 * @author xiaozhuang
 * @date 2022年03月20日 15:49
 */
@Configuration
@EnableSwagger2
public class SwaggerAutoConfiguration {
    @Bean
    public Docket createRestApi1() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                // 分组
                .apiInfo(apiInfo()).groupName("第一组接口")
                .select()
                // 扫描的包路径
                .apis(RequestHandlerSelectors.basePackage("com.xiaoteng.controller"))
                .build();
        return docket;
    }
/*
    @Bean
    public Docket createRestApi2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).groupName("第二组接口")
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.xiaoteng"))
                .build();
    }*/

    //构建 api文档的详细信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("API接口文档")
                //创建人
                .contact(new Contact("swagger测试", "http://www.baidu.com", ""))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}

通常用在控制器层和实体类，请看下面例子：

package com.xiaoteng.entity;

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

/**
 * @author xiaozhuang
 * @date 2022年03月20日 16:18
 */
@Data
@ApiModel(value = "用户实体类")
public class UserEntity {
    @ApiModelProperty(value = "用户名字")
    private String name;
    @ApiModelProperty(value = "用户地址")
    private String address;
}

package com.xiaoteng.controller;

import com.wf.captcha.ArithmeticCaptcha;
import com.wf.captcha.ChineseCaptcha;
import com.wf.captcha.base.Captcha;
import com.xiaoteng.entity.UserEntity;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;

import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

/**
 * @author xiaozhuang
 * @date 2022年03月20日 15:10
 */
@RestController
@RequestMapping("userlogin")
@Api(tags = "用户登录控制器")  //swagger API
public class LoginController {
    /**
     * 生成验证码，通过前端传入一个key，区分同一时间请求的验证码
     *
     * @param key
     */
    @ApiOperation(value = "获取验证码") //swagger API
    @GetMapping(value = "/captcha", produces = "image/png")
    public void creatCaptcha(@RequestParam(value = "key") String key,
                             HttpServletResponse response) throws IOException {
        // 算数验证码
        Captcha captcha = new ArithmeticCaptcha();
        // 文字验证码
        // Captcha captcha2=new ChineseCaptcha();
        // 生成的验证码
        String text = captcha.text();
        System.out.println("验证码 = " + text);
        // 返回图片类型
        response.setContentType(MediaType.IMAGE_PNG_VALUE);
        // 清除浏览器缓存
        response.setHeader(HttpHeaders.PRAGMA, "No-cache");
        response.setHeader(HttpHeaders.CACHE_CONTROL, "No-cache");
        // 缓存时间为0
        response.setDateHeader(HttpHeaders.EXPIRES, 0L);
        // 回写给前端图片
        captcha.out(response.getOutputStream());
    }
    @ApiOperation(value = "通过id获取用户")
    @PostMapping("/updateUser")
    public String getUserById(UserEntity user){
        return "ok";
    }
}