一. 首先Swagger是什么?

Swagger 是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)。總體目標(biāo)是使客戶(hù)端和文件系統(tǒng)作為服務(wù)器以同樣的速度來(lái)更新。文件的方法，參數(shù)和模型緊密集成到服務(wù)器端的代碼，允許API來(lái)始終保持同步。Swagger官方API文檔:https://swagger.io/

作用：  1. 接口的文檔在線(xiàn)自動(dòng)生成。  2. 功能測(cè)試。

Swagger的主見(jiàn)介紹:

 

 Swagger Codegen: 通過(guò)Codegen 可以將描述文件生成html格式和cwiki形式的接口文檔，同時(shí)也能生成多鐘語(yǔ)言的服務(wù)端和客戶(hù)端的代碼。支持通過(guò)jar包，docker，node等方式在本地化執(zhí)行生成。也可以在后面的Swagger Editor中在線(xiàn)生成。

  Swagger UI: 提供了一個(gè)可視化的UI頁(yè)面展示描述文件。接口的調(diào)用方、測(cè)試、項(xiàng)目經(jīng)理等都可以在該頁(yè)面中對(duì)相關(guān)接口進(jìn)行查閱和做一些簡(jiǎn)單的接口請(qǐng)求。該項(xiàng)目支持在線(xiàn)導(dǎo)入描述文件和本地部署UI項(xiàng)目。

  Swagger Editor: 類(lèi)似于markendown編輯器的編輯Swagger描述文件的編輯器，該編輯支持實(shí)時(shí)預(yù)覽描述文件的更新效果。也提供了在線(xiàn)編輯器和本地部署編輯器兩種方式。

  Swagger Inspector: 感覺(jué)和postman差不多，是一個(gè)可以對(duì)接口進(jìn)行測(cè)試的在線(xiàn)版的postman。比在Swagger UI里面做接口請(qǐng)求，會(huì)返回更多的信息，也會(huì)保存你請(qǐng)求的實(shí)際請(qǐng)求參數(shù)等數(shù)據(jù)。

  Swagger Hub: 集成了上面所有項(xiàng)目的各個(gè)功能，你可以以項(xiàng)目和版本為單位，將你的描述文件上傳到Swagger Hub中。在Swagger Hub中可以完成上面項(xiàng)目的所有工作，需要注冊(cè)賬號(hào)，分免費(fèi)版和收費(fèi)版。

PS：  Springfox Swagger: Spring 基于 swagger 規(guī)范，可以將基于 SpringMVC 和 Spring Boot 項(xiàng)目的項(xiàng)目代碼，自動(dòng)生成 JSON 格式的描述文件。本身不是屬于 Swagger 官網(wǎng)提供的，在這里列出來(lái)做個(gè)說(shuō)明，方便后面作一個(gè)使用的展開(kāi)。

二. Swagger UI的使用:

Swagger注解解釋:

@Api：請(qǐng)求類(lèi)的說(shuō)明@Api：放在 請(qǐng)求的類(lèi)上，與 @Controller 并列，說(shuō)明類(lèi)的作用，如用戶(hù)模塊，訂單類(lèi)等。tags='說(shuō)明該類(lèi)的作用'value='該參數(shù)沒(méi)什么意義，所以不需要配置'

常用注解： - @Api()用于類(lèi)； 表示標(biāo)識(shí)這個(gè)類(lèi)是swagger的資源 - @ApiOperation()用于方法； 表示一個(gè)http請(qǐng)求的操作 - @ApiParam()用于方法，參數(shù)，字段說(shuō)明； 表示對(duì)參數(shù)的添加元數(shù)據(jù)（說(shuō)明或是否必填等） - @ApiModel()用于類(lèi) 表示對(duì)類(lèi)進(jìn)行說(shuō)明，用于參數(shù)用實(shí)體類(lèi)接收 - @ApiModelProperty()用于方法，字段 表示對(duì)model屬性的說(shuō)明或者數(shù)據(jù)操作更改 - @ApiIgnore()用于類(lèi)，方法，方法參數(shù) 表示這個(gè)方法或者類(lèi)被忽略 - @ApiImplicitParam() 用于方法 表示單獨(dú)的請(qǐng)求參數(shù) - @ApiImplicitParams() 用于方法包含多個(gè) @ApiImplicitParam

(1). @Api: 請(qǐng)求類(lèi)的說(shuō)明

@Api：放在 請(qǐng)求的類(lèi)上，與 @Controller 并列，說(shuō)明類(lèi)的作用，如用戶(hù)模塊，訂單類(lèi)等。tags='說(shuō)明該類(lèi)的作用'value='描述該類(lèi)作用' [推薦用這個(gè)]@Api 其它屬性配置：屬性名稱(chēng) 備注value url的路徑值tags 如果設(shè)置這個(gè)值、value的值會(huì)被覆蓋description 對(duì)api資源的描述basePath 基本路徑position 如果配置多個(gè)Api 想改變顯示的順序位置produces 如, “application/json, application/xml”consumes 如, “application/json, application/xml”protocols 協(xié)議類(lèi)型，如: http, https, ws, wss.authorizations 高級(jí)特性認(rèn)證時(shí)配置hidden 配置為true ，將在文檔中隱藏

(2). @ApiOperation：方法的說(shuō)明

@ApiOperation：'用在請(qǐng)求的方法上，說(shuō)明方法的作用' value='說(shuō)明方法的作用' notes='方法的備注說(shuō)明'

(3). @ApiImplicitParams、@ApiImplicitParam：方法參數(shù)的說(shuō)明

@ApiImplicitParams：用在請(qǐng)求的方法上，包含一組參數(shù)說(shuō)明@ApiImplicitParam：對(duì)單個(gè)參數(shù)的說(shuō)明 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（請(qǐng)求體）--> @RequestBody User user· form（普通表單提交） dataType：參數(shù)類(lèi)型，默認(rèn)String，其它值dataType='Integer' defaultValue：參數(shù)的默認(rèn)值

示例:

@Api(tags='用戶(hù)模塊')@Controllerpublic class UserController {@ApiOperation(value='用戶(hù)登錄',notes='隨邊說(shuō)點(diǎn)啥')@ApiImplicitParams({@ApiImplicitParam(name='mobile',value='手機(jī)號(hào)',required=true,paramType='form'),@ApiImplicitParam(name='password',value='密碼',required=true,paramType='form'),@ApiImplicitParam(name='age',value='年齡',required=true,paramType='form',dataType='Integer')})@PostMapping('/login')public JsonResult login(@RequestParam String mobile, @RequestParam String password,@RequestParam Integer age){//... return JsonResult.ok(map);}}

(4). @ApiResponses、@ApiResponse：方法返回值的說(shuō)明

@ApiResponses：方法返回對(duì)象的說(shuō)明@ApiResponse：每個(gè)參數(shù)的說(shuō)明 code：數(shù)字，例如400 message：信息，例如'請(qǐng)求參數(shù)沒(méi)填好' response：拋出異常的類(lèi)

(5). @ApiModel：用于JavaBean上面，表示一個(gè)JavaBean（如：響應(yīng)數(shù)據(jù)）的信息

@ApiModel：用于JavaBean的類(lèi)上面，表示此 JavaBean 整體的信息（這種一般用在post創(chuàng)建的時(shí)候，使用 @RequestBody 這樣的場(chǎng)景，請(qǐng)求參數(shù)無(wú)法使用 @ApiImplicitParam 注解進(jìn)行描述的時(shí)候 ）

(6). @ApiModelProperty：用在JavaBean類(lèi)的屬性上面，說(shuō)明屬性的含義

@ApiModel(description= '返回響應(yīng)數(shù)據(jù)')public class RestMessage implements Serializable{@ApiModelProperty(value = '是否成功')private boolean success=true;@ApiModelProperty(value = '返回對(duì)象')private Object data;@ApiModelProperty(value = '錯(cuò)誤編號(hào)')private Integer errCode;@ApiModelProperty(value = '錯(cuò)誤信息')private String message;/* getter/setter 略*/}三. Swagger整合SpringBoot1. Pom依賴(lài):

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version></dependency><dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.2.2</version></dependency>2. 配置類(lèi):

package com.zhiyou100.configBeans;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.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;/** * @Author ZhengZiXuan * @Desc */@Configuration // @Configuration注解，讓Spring來(lái)加載該類(lèi)配置。@EnableSwagger2 //@EnableSwagger2注解來(lái)啟用Swagger2public class SwaggerConfigBean { /** * 創(chuàng)建API應(yīng)用 * apiInfo() 增加API相關(guān)信息 * 通過(guò)select()函數(shù)返回一個(gè)ApiSelectorBuilder實(shí)例,用來(lái)控制哪些接口暴露給Swagger來(lái)展現(xiàn)， * 本例采用指定掃描的包路徑來(lái)定義指定要建立API的目錄。 * * @return */ @Bean public Docket createRestApi(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage('com.zhiyou100.controller')).paths(PathSelectors.any()).build(); } /** * 創(chuàng)建該API的基本信息（這些基本信息會(huì)展現(xiàn)在文檔頁(yè)面中） * 訪(fǎng)問(wèn)地址：http://項(xiàng)目實(shí)際地址/swagger-ui.html * @return */ private ApiInfo apiInfo() {return new ApiInfoBuilder().title('使用Swagger2 構(gòu)建RESTful APIS - 廢物').description('廢物 - Swagger使用演示').termsOfServiceUrl('www.zzxBIuBIuBIu.com').version('1.0').build(); }}3. 正常的Controller再加Swagger注解:

package com.zhiyou100.controller;import io.swagger.annotations.Api;import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiOperation;import org.springframework.stereotype.Controller;import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.bind.annotation.ResponseBody;/** * @Author ZhengZiXuan * @Desc */@Controller@Api('測(cè)試Swagger 的Controller類(lèi)')public class TestController { @ApiOperation(value='根據(jù)id查詢(xún)名字',notes = '備注:無(wú)') @ApiImplicitParam(name = 'id',value = '用戶(hù)id',required = true, paramType = 'query',dataType = 'Integer') @RequestMapping('/getNameById') @ResponseBody public String getNameById(int id){return '張三'; }}

4.啟動(dòng)測(cè)試:

http://localhost:8080/swagger-ui.html

四. 訪(fǎng)問(wèn)404Bug的解決方法

Swagger UI 界面介紹:

五. Model對(duì)象增刪改查演示

對(duì)User類(lèi)實(shí)現(xiàn)增刪改查,生成api文檔

package com.zhiyou100.model;/** * @Author ZhengZiXuan * @Date 2021/05/10 * @Desc */public class User { private int id; private String name; private String password; @Override public String toString() {return 'User{' +'id=' + id +', name=’' + name + ’’’ +', password=’' + password + ’’’ +’}’; } public User() { } public int getId() {return id; } public void setId(int id) {this.id = id; } public String getName() {return name; } public void setName(String name) {this.name = name; } public String getPassword() {return password; } public void setPassword(String password) {this.password = password; } public User(int id, String name, String password) {this.id = id;this.name = name;this.password = password; }}

package com.zhiyou100.controller;import com.zhiyou100.model.User;import io.swagger.annotations.Api;import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiImplicitParams;import io.swagger.annotations.ApiOperation;import org.springframework.web.bind.annotation.*;import java.util.ArrayList;import java.util.List;/** * @Author ZhengZiXuan * @Date 2021/05/10 * @Desc 有點(diǎn)BUG 就是list集合中的增刪改 */@RestController@Api('User類(lèi)的增刪改查API')public class UserController { ArrayList<User> users = null; public UserController(){users = new ArrayList<>();users.add(new User(1,'張三','123'));users.add(new User(2,'李四','1234'));users.add(new User(3,'王五','12345'));System.out.println('init users '+users); } /** * 根據(jù)id查User */ @ApiOperation('根據(jù)id查用戶(hù)') @ApiImplicitParam(name = 'id',value = '用戶(hù)id', required = true,paramType = 'path',dataType = 'Integer') @RequestMapping(value='/user/get/{id}',method = RequestMethod.GET) public User getUserById(@PathVariable('id') Integer id){System.out.println('getUserById id: '+id);if (id != null){ if (id>0 && id <4){User user = users.get(id);System.out.println('getUserById User: '+user);return user; }}return null; } /** * 查全部user */ @ApiOperation('查詢(xún)?nèi)坑脩?hù)') @RequestMapping(value='/user/get',method = RequestMethod.GET) public List<User> getAllUser(){System.out.println('getAllUser');return users; } /** * 添加User */ @ApiOperation('添加用戶(hù)') @ApiImplicitParam(name='user',value = '用戶(hù)對(duì)象',paramType = 'body',dataType = 'User') @RequestMapping(value='/user/add',method = RequestMethod.POST) public User addUser(@RequestBody User user){System.out.println('addUser User:'+user);if (user == null || user.getId() == 0){ return null;}users.add(user);return user; } /** * 刪除User */ @ApiOperation('根據(jù)id刪除用戶(hù)') @ApiImplicitParam(name = 'id',value = '用戶(hù)id', required = true,paramType = 'path', dataType = 'Integer') @RequestMapping(value='/user/delete/{id}',method = RequestMethod.DELETE) public boolean delUserById(@PathVariable('id') Integer id){System.out.println('delUserById id:'+id);if (id != null){ users.remove(id); return true;}return false; } /** * 更新User */ @ApiOperation('根據(jù)id更新用戶(hù)') @ApiImplicitParams({ @ApiImplicitParam(name = 'id',value = '用戶(hù)id', required = true,paramType = 'path', dataType = 'Integer'), @ApiImplicitParam(name = 'user',value = '用戶(hù)對(duì)象', required = true,paramType = 'body', dataType = 'User')}) @RequestMapping(value='/user/update/{id}',method = RequestMethod.PUT) public boolean UpdateUserById(@PathVariable('id') Integer id,@RequestBody User user){System.out.println('UpdateUserById id:'+id+' , User:'+user);if (id != null && user != null){ users.add(id,user); return true;}return false; }}

1. 查詢(xún)?nèi)?

2. 根據(jù)id查:

3. 添加用戶(hù):

4.更新用戶(hù):

5. 刪除用戶(hù):

到此這篇關(guān)于在SpringBoot項(xiàng)目中的使用Swagger的方法示例的文章就介紹到這了,更多相關(guān)SpringBoot使用Swagger內(nèi)容請(qǐng)搜索好吧啦網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持好吧啦網(wǎng)！