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";
    }
}

默認訪問地址：http://localhost:8080/swagger-ui.html

效果如下：