SpringBoot中使用Swagger生成RestFul規(guī)范API文檔

1. 在pom.xml文件中添加依賴

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

2. 創(chuàng)建swagger配置類

package com.bitzh.config;


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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger 配置文件
 */
@Configuration      //標記為配置類
@EnableSwagger2     //開啟swagger
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.bitzh.controller"))
                //basePackage可以指定生成api的包,指定的包下面的controller類中的requestMapping方法會生成api解釋
                .paths(PathSelectors.any())
                .build();
    }

    //配置封面信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("圖書管理系統(tǒng)接口文檔")            //封面標題
                .description("此文檔描述了****")         //文檔描述
                .contact(new Contact("張三","www.abc142162.com","z5123451@163.com"))  //聯(lián)系人
                .version("1.0")     //版本號
                .build();
    }
}

封面效果

3. 為controller哗戈、requestMapping方法及其中的參數添加詳細解釋

package com.bitzh.controller;


import com.bitzh.entity.User;
import com.bitzh.service.UserService;
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 javax.annotation.Resource;

@RestController
@Api(tags = "用戶信息管理接口")
public class UserController {

    @Resource
    private UserService userService;


    @RequestMapping(value = "/test/{id}",method = RequestMethod.GET)
    @ApiOperation(value = "根據ID查詢用戶",notes = "根據ID查詢用戶，返回用戶對象")
    @ApiImplicitParam(name = "id",value = "用戶ID",required = true,dataType = "int")
    public User getUser(@PathVariable("id") int userId){
        User user = userService.queryUserByUserId(userId);
        return user;
    }

    @GetMapping("/test/{userId}/{userName}")
    @ApiOperation(value = "打印用戶信息",notes = "打印出用戶的ID和用戶名")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userId",value = "用戶ID",required = true,dataType = "int"),
            @ApiImplicitParam(name = "userName",value = "用戶名",required = true,dataType = "string")
    })
    public void printUser(@PathVariable("userId") int userId,@PathVariable("userName") String userName){
        System.out.println(userId+userId);
    }
}

實現效果

4. 為實體類添加詳細描述

package com.bitzh.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * 對實體對象添加詳細描述
 */
@Data
@ApiModel(value = "user對象",description = "用戶信息")
public class User {
    @ApiModelProperty(value = "用戶ID",dataType = "int",required = true)
    private int userId;
    @ApiModelProperty(value = "用戶名",dataType = "string",required = true)
    private String userName;
    @ApiModelProperty(value = "用戶密碼",dataType = "string",required = true)
    private String userPwd;
    @ApiModelProperty(value = "鹽",dataType = "string")
    private String pwdSalt;
}

實現效果

啟動服務器，訪問：http://localhost:8080/swagger-ui.html
獲取生成的api文檔

常用類解釋

1. @Api
用在controller上悔捶，說明該controller的作用
@Api(value = "用戶信息管理接口")

2. @ApiOperation
用在方法上，說明方法的作用
@ApiOperation(value = "根據ID查找用戶", notes = "調用此接口的注意事項", httpMethod = "GET")

3 @ApiImplicitParams
用在方法上包含一組參數說明世蔗，例如：

@ApiImplicitParams({
@ApiImplicitParam(name = "userId",value = "用戶ID",required = true,dataType = "int"),
@ApiImplicitParam(name = "userName",value = "用戶名",required = true,dataType = "string")

})

4. @ApiImplicitParam
用在@ApiImplicitParams注解中嚎幸，指定一個請求參數的各個方面

paramType：參數放在哪個地方

header（參數放在請求頭中）–>請求參數的獲取：@RequestHeader
query（參數放在url中洗贰，例如findUser.action?userId=1）–>請求參數的獲日裔：@RequestParam
path（用于restful接口，例如/user/1）–>請求參數的獲攘沧獭：@PathVariable

name：參數名
dataType：參數類型
required：參數是否必須傳
value：參數的意思
defaultValue：參數的默認值

5. @ApiModel
描述一個Model的信息（這種一般用在post創(chuàng)建的時候许布，使用@RequestBody這樣的場景，請求參數無法使用@ApiImplicitParam注解進行描述的時候）绎晃，例如

@ApiModel(value = "用戶實體類",description = "用戶信息")
public class User {
}

6. @ApiModelProperty
描述一個model的屬性蜜唾，例如

@ApiModelProperty(value = "用戶ID",dataType = "int",required = true)
private int userId;