我們已經開發完了一個用戶註冊的接口,但是我們並沒有測試也不知道里面哪裏忽略了,有什麼問題,先講下下swagger2,然後集成到spring boot這個項目中。源碼:https://github.com/limingios/wxProgram.git 中的wx-springboot
swagger2
介紹
swagger2 是可以構建一個非常強大的,是個非常好用的工具也是個非常好用的插件。
可以生成文檔形式的api並提供給不同的團隊
便於自測,也便於領導查閱任務量。
無需過多冗餘的word文檔。保證文檔是最新的。
使用方法
在spring boot common中pom中引入
<!-- swagger2 配置 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.4.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.4.0</version> </dependency>
添加swagger2的配置文件
在spring boot api中加入java類
package com.idig8; import java.util.ArrayList; import java.util.List; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.ParameterBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.schema.ModelRef; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.service.Parameter; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class Swagger2 { /** * @Description:swagger2的配置文件,這裏可以配置swagger2的一些基本的內容,比如掃描的包等等 */ @Bean public Docket createRestApi() { // 爲swagger添加header參數可供輸入 ParameterBuilder userTokenHeader = new ParameterBuilder(); ParameterBuilder userIdHeader = new ParameterBuilder(); List<Parameter> pars = new ArrayList<Parameter>(); userTokenHeader.name("headerUserToken").description("userToken") .modelRef(new ModelRef("string")).parameterType("header") .required(false).build(); userIdHeader.name("headerUserId").description("userId") .modelRef(new ModelRef("string")).parameterType("header") .required(false).build(); pars.add(userTokenHeader.build()); pars.add(userIdHeader.build()); return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() .apis(RequestHandlerSelectors.basePackage("com.idig8.controller")) .paths(PathSelectors.any()).build() .globalOperationParameters(pars); } /** * @Description: 構建 api文檔的信息 */ private ApiInfo apiInfo() { return new ApiInfoBuilder() // 設置頁面標題 .title("使用swagger2構建小程序後端api接口文檔") // 設置聯繫人 .contact(new Contact("IT人故事會", "https://idig8.com", "公衆號:編程坑太多")) // 描述 .description("歡迎訪問接口文檔") // 定義版本號 .version("1.0").build(); } }
修改原有的controller的修改
package com.idig8.controller; import org.apache.commons.lang3.StringUtils; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RestController; import com.github.pagehelper.util.StringUtil; import com.idig8.pojo.Users; import com.idig8.service.UserService; import com.idig8.utils.JSONResult; import com.idig8.utils.MD5Utils; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; @RestController @Api(value="用戶註冊登錄的接口",tags={"註冊和登錄的controller"}) public class RegistLoginController { @Autowired private UserService userService; @ApiOperation(value="用戶註冊",notes="用戶註冊的接口") @PostMapping("/regist") public JSONResult regist(@RequestBody Users user) { //1.判斷用戶名和密碼不能爲空 if(StringUtils.isBlank(user.getUsername())||StringUtils.isBlank(user.getPassword())) { return JSONResult.errorMsg("用戶名或密碼不能爲空"); } //2.判斷用戶名是否存在 boolean usernameIsExist = userService.queryUsernameIsExist(user.getUsername()); if(!usernameIsExist) { user.setNickname(user.getUsername()); try { user.setPassword(MD5Utils.getMD5Str(user.getPassword())); } catch (Exception e) { return JSONResult.errorMsg(e.getMessage()); } user.setFollowCounts(0); user.setReceiveLikeCounts(0); user.setFansCounts(0); userService.saveUser(user); }else { return JSONResult.errorMsg("用戶名或已經存在,請更換在試試!"); } return JSONResult.ok(); } }
增加Users屬性的限制,那些必填 ,spring-boot pojo項目
package com.idig8.pojo; import javax.persistence.*; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; @ApiModel(value="用戶對象",description="這是用戶對象") public class Users { @Id @ApiModelProperty(hidden=true) private String id; /** * 用戶名 */ @ApiModelProperty(value="用戶名",name="username",example="idig8",required=true) private String username; /** * 密碼 */ @ApiModelProperty(value="密碼",name="password",example="123456",required=true) private String password; /** * 我的頭像,如果沒有默認給一張 */ @Column(name = "face_image") private String faceImage; /** * 暱稱 */ @ApiModelProperty(hidden=true) private String nickname; /** * 我的粉絲數量 */ @ApiModelProperty(hidden=true) @Column(name = "fans_counts") private Integer fansCounts; /** * 我關注的人總數 */ @ApiModelProperty(hidden=true) @Column(name = "follow_counts") private Integer followCounts; /** * 我接受到的讚美/收藏 的數量 */ @ApiModelProperty(hidden=true) @Column(name = "receive_like_counts") private Integer receiveLikeCounts; /** * @return id */ public String getId() { return id; } /** * @param id */ public void setId(String id) { this.id = id; } /** * 獲取用戶名 * * @return username - 用戶名 */ public String getUsername() { return username; } /** * 設置用戶名 * * @param username 用戶名 */ public void setUsername(String username) { this.username = username; } /** * 獲取密碼 * * @return password - 密碼 */ public String getPassword() { return password; } /** * 設置密碼 * * @param password 密碼 */ public void setPassword(String password) { this.password = password; } /** * 獲取我的頭像,如果沒有默認給一張 * * @return face_image - 我的頭像,如果沒有默認給一張 */ public String getFaceImage() { return faceImage; } /** * 設置我的頭像,如果沒有默認給一張 * * @param faceImage 我的頭像,如果沒有默認給一張 */ public void setFaceImage(String faceImage) { this.faceImage = faceImage; } /** * 獲取暱稱 * * @return nickname - 暱稱 */ public String getNickname() { return nickname; } /** * 設置暱稱 * * @param nickname 暱稱 */ public void setNickname(String nickname) { this.nickname = nickname; } /** * 獲取我的粉絲數量 * * @return fans_counts - 我的粉絲數量 */ public Integer getFansCounts() { return fansCounts; } /** * 設置我的粉絲數量 * * @param fansCounts 我的粉絲數量 */ public void setFansCounts(Integer fansCounts) { this.fansCounts = fansCounts; } /** * 獲取我關注的人總數 * * @return follow_counts - 我關注的人總數 */ public Integer getFollowCounts() { return followCounts; } /** * 設置我關注的人總數 * * @param followCounts 我關注的人總數 */ public void setFollowCounts(Integer followCounts) { this.followCounts = followCounts; } /** * 獲取我接受到的讚美/收藏 的數量 * * @return receive_like_counts - 我接受到的讚美/收藏 的數量 */ public Integer getReceiveLikeCounts() { return receiveLikeCounts; } /** * 設置我接受到的讚美/收藏 的數量 * * @param receiveLikeCounts 我接受到的讚美/收藏 的數量 */ public void setReceiveLikeCounts(Integer receiveLikeCounts) { this.receiveLikeCounts = receiveLikeCounts; } }
運行項目
報錯:沒有增加掃描
Action: Consider defining a bean of type 'com.idig8.mapper.UsersMapper' in your configuration.
增加id自動生成Sid的掃描,在service裏面注入了和mapper的掃描
package com.idig8; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.context.annotation.ComponentScan; import tk.mybatis.spring.annotation.MapperScan; @SpringBootApplication @MapperScan(basePackages="com.idig8.mapper") @ComponentScan(basePackages= {"com.idig8","org.n3r.idworker"}) public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }
訪問網址http://localhost:8081/swagger-ui.html
點擊左邊的實例,修改內容,點擊try it out!
返回的結果
數據庫插入正常
裏面的內容設置成空
用戶名設置成idig8 在試試接口
PS:到這裏swagger2的文檔配置和接口配置,包括錯誤的的接口測試基本都演示完畢了。