前言

前一章節(jié)介紹了mybatisPlus的集成和簡(jiǎn)單使用，本章節(jié)開(kāi)始接著上一章節(jié)的用戶表，進(jìn)行Swagger2的集成�，F(xiàn)在都奉行前后端分離開(kāi)發(fā)和微服務(wù)大行其道，分微服務(wù)及前后端分離后，前后端開(kāi)發(fā)的溝通成本就增加了。所以一款強(qiáng)大的RESTful API文檔就至關(guān)重要了。而目前在后端領(lǐng)域，基本上是Swagger的天下了。

Swagger2介紹

Swagger是一款RESTful接口的文檔在線自動(dòng)生成、功能測(cè)試功能框架。一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化RESTful風(fēng)格的Web服務(wù)，加上swagger-ui，可以有很好的呈現(xiàn)。

SpringBoot集成

這里選用的swagger版本為：2.8.0

0.pom依賴

<!--swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

1.編寫(xiě)配置文件(Swagger2Config.java)

主要是添加注解@EnableSwagger2和定義Docket的bean類(lèi)。

@EnableSwagger2
@Configuration
public class SwaggerConfig {

    //是否開(kāi)啟swagger，正式環(huán)境一般是需要關(guān)閉的，可根據(jù)springboot的多環(huán)境配置進(jìn)行設(shè)置
    @Value(value = "${swagger.enabled}")
    Boolean swaggerEnabled;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                // 是否開(kāi)啟
                .enable(swaggerEnabled).select()
                // 掃描的路徑包
                .apis(RequestHandlerSelectors.basePackage("cn.lqdev.learning.springboot.chapter10"))
                // 指定路徑處理PathSelectors.any()代表所有的路徑
                .paths(PathSelectors.any()).build().pathMapping("/");
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot-Swagger2集成和使用-demo示例")
                .description("oKong | 趔趄的猿")
                // 作者信息
                .contact(new Contact("oKong", "https://blog.lqdev.cn/", "499452441@qq.com"))
                .version("1.0.0")
                .build();
    }
}

3.添加文檔內(nèi)容(一般上是在Controller，請(qǐng)求參數(shù)上進(jìn)行注解，這里以上章節(jié)的UserController進(jìn)行配置)

UserController

/**
 * 用戶控制層 簡(jiǎn)單演示增刪改查及分頁(yè)
 * 新增了swagger文檔內(nèi)容 2018-07-21
 * @author oKong
 *
 */
@RestController
@RequestMapping("/user")
@Api(tags="用戶API")
public class UserController {

    @Autowired
    IUserService userService;

    @PostMapping("add")
    @ApiOperation(value="用戶新增")
    //正常業(yè)務(wù)時(shí)， 需要在user類(lèi)里面進(jìn)行事務(wù)控制，控制層一般不進(jìn)行業(yè)務(wù)控制的。
    //@Transactional(rollbackFor = Exception.class)
    public Map<String,String> addUser(@Valid @RequestBody UserReq userReq){

        User user = new User();
        user.setCode(userReq.getCode());
        user.setName(userReq.getName());
        //由于設(shè)置了主鍵策略 id可不用賦值 會(huì)自動(dòng)生成
        //user.setId(0L);
        userService.insert(user);
        Map<String,String> result = new HashMap<String,String>();
        result.put("respCode", "01");
        result.put("respMsg", "新增成功");
        //事務(wù)測(cè)試
        //System.out.println(1/0);
        return result;
    }

    @PostMapping("update")
    @ApiOperation(value="用戶修改")    
    public Map<String,String> updateUser(@Valid @RequestBody UserReq userReq){

        if(userReq.getId() == null || "".equals(userReq.getId())) {
            throw new CommonException("0000", "更新時(shí)ID不能為空");
        }
        User user = new User();
        user.setCode(userReq.getCode());
        user.setName(userReq.getName());
        user.setId(Long.parseLong(userReq.getId()));        
        userService.updateById(user);
        Map<String,String> result = new HashMap<String,String>();
        result.put("respCode", "01");
        result.put("respMsg", "更新成功");
        return result;
    }

    @GetMapping("/get/{id}")
    @ApiOperation(value="用戶查詢(ID)")    
    @ApiImplicitParam(name="id",value="查詢ID",required=true)
    public Map<String,Object> getUser(@PathVariable("id") String id){
        //查詢
        User user = userService.selectById(id);
        if(user == null) {
            throw new CommonException("0001", "用戶ID：" + id + "，未找到");
        }
        UserResp resp = UserResp.builder()
                .id(user.getId().toString())
                .code(user.getCode())
                .name(user.getName())
                .status(user.getStatus())
                .build();
        Map<String,Object> result = new HashMap<String,Object>();
        result.put("respCode", "01");
        result.put("respMsg", "成功");
        result.put("data", resp);
        return result;
    }

    @GetMapping("/page")
    @ApiOperation(value="用戶查詢(分頁(yè))")        
    public Map<String,Object> pageUser(int current, int size){
        //分頁(yè)
        Page<User> page = new Page<>(current, size);
        Map<String,Object> result = new HashMap<String,Object>();
        result.put("respCode", "01");
        result.put("respMsg", "成功");
        result.put("data", userService.selectPage(page));
        return result;
    }

}

UserReq.java

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
//加入@ApiModel
@ApiModel
public class UserReq {

    @ApiModelProperty(value="ID",dataType="String",name="ID",example="1020332806740959233")
    String id;

    @ApiModelProperty(value="編碼",dataType="String",name="code",example="001")
    @NotBlank(message = "編碼不能為空")
    String code;

    @ApiModelProperty(value="名稱",dataType="String",name="name",example="oKong")
    @NotBlank(message = "名稱不能為空")
    String name;
}

Swagger訪問(wèn)與使用

api首頁(yè)路徑：http://127.0.0.1:8080/swagger-ui.html

調(diào)試：點(diǎn)擊需要訪問(wèn)的api列表，點(diǎn)擊try it out!按鈕，即可彈出一下頁(yè)面：

執(zhí)行：

結(jié)果：

大家可下載示例，查看自定義的字符出現(xiàn)的位置，這樣可以對(duì)其有個(gè)大致了解，各字段的作用領(lǐng)域是哪里。

Swagger常用屬性說(shuō)明

常用的注解@Api、@ApiOperation、@ApiModel、@ApiModelProperty示例中有進(jìn)行標(biāo)注，對(duì)于其他注解，大家可自動(dòng)谷歌，畢竟常用的就這幾個(gè)了。有了swagger之后，原本一些post請(qǐng)求需要postman這樣的調(diào)試工具來(lái)進(jìn)行發(fā)起，而現(xiàn)在直接在頁(yè)面上就可以進(jìn)行調(diào)試了，是不是很爽！對(duì)于服務(wù)的調(diào)用者而已，有了這份api文檔也是一目了然，不需要和后端多少溝通成本，按著api說(shuō)明進(jìn)行前端開(kāi)發(fā)即可。

總結(jié)

本章節(jié)主要是對(duì)Swagger的集成和簡(jiǎn)單使用進(jìn)行了說(shuō)明，詳細(xì)的用法，可自行搜索相關(guān)資料下，這里就不闡述了。因?yàn)閷?duì)于百分之八十之上的文檔要求基本能滿足了。一些比如前端根據(jù)swagger的api-docs進(jìn)行前端的快速開(kāi)發(fā)，這就需要實(shí)際情況實(shí)際約定了，比如快速的生成表單頁(yè)等也是很方便的事情。最后，強(qiáng)烈建議在生產(chǎn)環(huán)境關(guān)閉swagger,避免不必要的漏洞暴露！

最后

目前互聯(lián)網(wǎng)上很多大佬都有SpringBoot系列教程，如有雷同，請(qǐng)多多包涵了。本文是作者在電腦前一字一句敲的，每一步都是實(shí)踐的。若文中有所錯(cuò)誤之處，還望提出，謝謝。

標(biāo)簽： isp 谷歌 互聯(lián)網(wǎng) 漏洞 搜索

版權(quán)申明：本站文章部分自網(wǎng)絡(luò)，如有侵權(quán)，請(qǐng)聯(lián)系：west999com@outlook.com
特別注意：本站所有轉(zhuǎn)載文章言論不代表本站觀點(diǎn)！
本站所提供的圖片等素材，版權(quán)歸原作者所有，如需使用，請(qǐng)與原作者聯(lián)系。