前后端分離的項(xiàng)目，接口文檔的存在十分重要。與手動(dòng)編寫(xiě)接口文檔不同，swagger是一個(gè)自動(dòng)生成接口文檔的工具，在需求不斷變更的環(huán)境下，手動(dòng)編寫(xiě)文檔的效率實(shí)在太低。與新版的swagger3相比swagger2配置更少，使用更加方便。

一、pom文件中引入Swagger3依賴(lài)

<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的配置

@Configurationpublic 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('更多請(qǐng)咨詢(xún)服務(wù)開(kāi)發(fā)者Ray。').contact(new Contact('Ray。', 'http://www.ruiyeclub.cn', 'ruiyeclub@foxmail.com')).version('1.0').build(); }}

四、Swagger注解的使用說(shuō)明

@Api：用在請(qǐng)求的類(lèi)上，表示對(duì)類(lèi)的說(shuō)明 tags='說(shuō)明該類(lèi)的作用，可以在UI界面上看到的注解' value='該參數(shù)沒(méi)什么意義，在UI界面上也看到，所以不需要配置'@ApiOperation：用在請(qǐng)求的方法上，說(shuō)明方法的用途、作用 value='說(shuō)明方法的用途、作用' notes='方法的備注說(shuō)明'@ApiImplicitParams：用在請(qǐng)求的方法上，表示一組參數(shù)說(shuō)明 @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個(gè)請(qǐng)求參數(shù)的各個(gè)方面 name：參數(shù)名 value：參數(shù)的漢字說(shuō)明、解釋 required：參數(shù)是否必須傳 paramType：參數(shù)放在哪個(gè)地方 · header --> 請(qǐng)求參數(shù)的獲取：@RequestHeader · query --> 請(qǐng)求參數(shù)的獲取：@RequestParam · path（用于restful接口）--> 請(qǐng)求參數(shù)的獲取：@PathVariable · body（不常用） · form（不常用） dataType：參數(shù)類(lèi)型，默認(rèn)String，其它值dataType='Integer'defaultValue：參數(shù)的默認(rèn)值@ApiResponses：用在請(qǐng)求的方法上，表示一組響應(yīng) @ApiResponse：用在@ApiResponses中，一般用于表達(dá)一個(gè)錯(cuò)誤的響應(yīng)信息 code：數(shù)字，例如400 message：信息，例如'請(qǐng)求參數(shù)沒(méi)填好' response：拋出異常的類(lèi)@ApiModel：用于響應(yīng)類(lèi)上，表示一個(gè)返回響應(yīng)數(shù)據(jù)的信息 （這種一般用在post創(chuàng)建的時(shí)候，使用@RequestBody這樣的場(chǎng)景， 請(qǐng)求參數(shù)無(wú)法使用@ApiImplicitParam注解進(jìn)行描述的時(shí)候） @ApiModelProperty：用在屬性上，描述響應(yīng)類(lèi)的屬性

Controller層的配置：

@Api(tags = '用戶(hù)信息管理')@RestController@RequestMapping('userRecord')public class UserRecordController extends ApiController { /** * 服務(wù)對(duì)象 */ @Resource private UserRecordService userRecordService; /** * 分頁(yè)查詢(xún)所有數(shù)據(jù) * @param page 分頁(yè)對(duì)象 * @param userRecord 查詢(xún)實(shí)體 * @return 所有數(shù)據(jù) */ @ApiOperation('分頁(yè)查詢(xún)所有數(shù)據(jù)') @GetMapping('page') public R selectAll(Page<UserRecord> page, UserRecord userRecord) { return success(this.userRecordService.page(page, new QueryWrapper<>(userRecord))); } /** * 通過(guò)主鍵查詢(xún)單條數(shù)據(jù) * @param id 主鍵 * @return 單條數(shù)據(jù) */ @ApiOperation('通過(guò)主鍵查詢(xún)單條數(shù)據(jù)') @GetMapping('{id}') public R selectOne(@PathVariable Serializable id) { return success(this.userRecordService.getById(id)); } /** * 新增數(shù)據(jù) * @param userRecord 實(shí)體對(duì)象 * @return 新增結(jié)果 */ @ApiOperation('新增數(shù)據(jù)') @PostMapping('insert') public R insert(@RequestBody UserRecord userRecord) { return success(this.userRecordService.save(userRecord)); } /** * 修改數(shù)據(jù) * @param userRecord 實(shí)體對(duì)象 * @return 修改結(jié)果 */ @ApiOperation('修改數(shù)據(jù)') @PutMapping('update') public R update(@RequestBody UserRecord userRecord) { return success(this.userRecordService.updateById(userRecord)); } /** * 刪除數(shù)據(jù) * @param idList 主鍵結(jié)合 * @return 刪除結(jié)果 */ @ApiOperation('刪除數(shù)據(jù)') @DeleteMapping('delete') public R delete(@RequestParam('idList') List<Long> idList) { return success(this.userRecordService.removeByIds(idList)); }}

五、Swagger界面效果

Swagger的訪問(wèn)路徑由port/swagger-ui.html改成了port/swagger-ui/ 或port/swagger-ui/index.html，項(xiàng)目演示代碼在springboot-swagger

以上就是本文的全部?jī)?nèi)容，希望對(duì)大家的學(xué)習(xí)有所幫助，也希望大家多多支持好吧啦網(wǎng)。