前後端分離的專案，介面檔案的存在十分重要。與手動編寫介面檔案不同，swagger是一個自動生成介面檔案的工具，在需求不斷變更的環境下，手動編寫檔案的效率實在太低。與swagger2相比新版的swagger3配置更少，使用更加方便。

一、pom檔案中引入Swagger3依賴

<dependency>

     <groupId>io.springfox</groupId>

      <artifactId>springfox-boot-starter</artifactId>

      <version>3.0.0</version>
 

</dependency>

二、Application上面加入@EnableOpenApi註解

@EnableOpenApi

@SpringBootApplication

@MapperScan(basePackages = {"cn.ruiyeclub.dao"})

public class Swagger3Application {

    public static void main(String[] args) {

        SpringApplication.run(Swagger3Application.class, args);

    }

}

三、Swagger3Config的配置

@Configuration

public class Swagger3Config {

    @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.OAS_30)

                .apiInfo(apiInfo())

                .select()

                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

                .paths(PathSelectors.any())
 

                .build();

    }

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()

                .title("Swagger3介面檔案")

                .description("更多請諮詢服務開發者Ray。")

                .contact(new Contact("Ray。", "http://www.ruiyeclub.cn", "[email protected]"))

                .version("1.0")

                .build();

    }

}

四、Swagger註解的使用說明

@Api：用在請求的類上，表示對類的說明

    tags="說明該類的作用，可以在UI介面上看到的註解"

    value="該引數沒什麼意義，在UI介面上也看到，所以不需要配置"

@ApiOperation：用在請求的方法上，說明方法的用途、作用

    value="說明方法的用途、作用"

    notes="方法的備註說明"

@ApiImplicitParams：用在請求的方法上，表示一組引數說明

    @ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求引數的各個方面

        name：引數名

        value：引數的漢字說明、解釋

        required：引數是否必須傳

        paramType：引數放在哪個地方

            · header --> 請求引數的獲取：@RequestHeader

            · query --> 請求引數的獲取：@RequestParam

            · path（用於restful介面）--> 請求引數的獲取：@PathVariable

            · body（不常用）

            · form（不常用）

        dataType：引數型別，預設String，其它值dataType="Integer"

        defaultValue：引數的預設值

@ApiResponses：用在請求的方法上，表示一組響應

    @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應資訊

        code：數字，例如400

        message：資訊，例如"請求引數沒填好"

        response：丟擲異常的類

@ApiModel：用於響應類上，表示一個返回響應資料的資訊

            （這種一般用在post建立的時候，使用@RequestBody這樣的場景，

            請求引數無法使用@ApiImplicitParam註解進行描述的時候）

    @ApiModelProperty：用在屬性上，描述響應類的屬性

Controller層的配置：

@Api(tags = "使用者資訊管理")

@RestController

@RequestMapping("userRecord")

public class UserRecordController extends ApiController {

    /**

     * 服務物件

     */

    @Resource

    private UserRecordService userRecordService;

    /**

     * 分頁查詢所有資料

     * @param page       分頁物件

     * @param userRecord 查詢實體

     * @return 所有資料

     */

    @ApiOperation("分頁查詢所有資料")

    @GetMapping("page")

    public R selectAll(Page<UserRecord> page, UserRecord userRecord) {

        return success(this.userRecordService.page(page, new QueryWrapper<>(userRecord)));

    }

    /**

     * 通過主鍵查詢單條資料

     * @param id 主鍵

     * @return 單條資料

     */

    @ApiOperation("通過主鍵查詢單條資料")

    @GetMapping("{id}")

    public R selectOne(@PathVariable Serializable id) {

        return success(this.userRecordService.getById(id));

    }

    /**

     * 新增資料

     * @param userRecord 實體物件

     * @return 新增結果

     */

    @ApiOperation("新增資料")

    @PostMapping("insert")

    public R insert(@RequestBody UserRecord userRecord) {

        return success(this.userRecordService.save(userRecord));

    }

    /**

     * 修改資料

     * @param userRecord 實體物件

     * @return 修改結果

     */

    @ApiOperation("修改資料")

    @PutMapping("update")

    public R update(@RequestBody UserRecord userRecord) {

        return success(this.userRecordService.updateById(userRecord));

    }

    /**

     * 刪除資料

     * @param idList 主鍵結合

     * @return 刪除結果

     */

    @ApiOperation("刪除資料")

    @DeleteMapping("delete")

    public R delete(@RequestParam("idList") List<Long> idList) {

        return success(this.userRecordService.removeByIds(idList));

    }

}

五、Swagger介面效果

Swagger的訪問路徑由port/swagger-ui.html改成了port/swagger-ui/ 或port/swagger-ui/index.html，專案演示程式碼在springboot-swagger