Swagger在項目中的應用

純手打……

前後端分離模式下,簡化對接,提交效率

對於後端開發人員,使用swagger維護在線接口文檔

spring集成了swagger,形成Spring-swagger項目

實際使用:

1:引入依賴:

        <!-- swagger核心組件,在代碼配置swagger時會依賴到它 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- swagger的用戶界面,用於展示api接口文檔 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>RELEASE</version>
        </dependency>
        <!--增加兩個配置目的:訪問swagger後臺報錯處理-->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.22</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.22</version>
        </dependency>

2 spring集成配置

/**
 * swagger
 *
 * @author l
 * @date 20190820
 */
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    /**
     * 創建Docket
     */
    @Bean
    public Docket createApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("api-user文檔")
                // 去掉swagger默認的狀態碼
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.api.web.swagger"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 構造ApiInfo
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("這是swagger的title")
                .description("這是swagger的描述")
                .version("1.0.0")
                .contact(new Contact("張三", "", ""))
                .build();
    }
}

此時,即可訪問 http://{ip}:{port}/doc.html

3 controller

/**
 * 用戶
 *
 * @author l
 * @date 20190820
 */
@Slf4j
@RestController
@RequestMapping(value = "/api/user")
@Api(tags = "用戶相關")
public class UserController {

    static Map<Integer, User> map = new HashMap<Integer, User>(){{
        put(1, new User().setId(1).setName("張三").setPhone("13566669999"));
        put(2, new User().setId(2).setName("李四").setPhone("15899996666"));
    }};

    /**
     *  查詢用戶
     */
    @GetMapping("/info")
    /** 定義swagger中接口說明 */
    @ApiOperation(value="根據id查詢用戶",notes="id必填,rest方式",consumes = "application/x-www-form-urlencoded")
    /** 定義swagger中的請求參數 */
    @ApiImplicitParams({
        @ApiImplicitParam(name="id",value="id",required=true,paramType="query",dataType = "int")
    })
    /** 定義接口返回信息 */
    @ApiResponses({@ApiResponse(code = 200,message = "OK")})
    public Result<User> info(Integer id){
        log.info("查詢id={}的用戶", id);
        return Result.ok(map.get(id));
    }

    /**
     *  查詢所有用戶
     *      swagger中的接口順序是以uri的字母順序生成
     */
    @GetMapping("/all")
    @ApiOperation(value="查詢所有用戶")
    public Result<List<User>> getAll(){
        List<User> list = new ArrayList<>();
        for (Map.Entry<Integer, User> entry : map.entrySet()) {
            list.add(entry.getValue());
        }
        return Result.ok(list);
    }

}

4 實體類user

/**
 *  用戶
 */
@Data
@Accessors(chain = true)
@ApiModel(description = "用戶實體")
public class User {
    @ApiModelProperty(value = "主鍵")
    private Integer id;
    @ApiModelProperty(value = "姓名")
    private String name;
    @ApiModelProperty(value = "手機號")
    private String phone;
}

5 實體類result

/**
 *  返回實體
 */
@Data
@Accessors(chain = true)
@ApiModel(description = "返回實體")
public class Result<T> {
    @ApiModelProperty(value = "狀態碼")
    private Integer code;
    @ApiModelProperty(value = "返回信息")
    private String message;
    @ApiModelProperty(value = "返回數據")
    private T datas;

    public static <T> Result<T> ok(T t){
        return new Result<T>().setCode(200).setMessage("ok").setDatas(t);
    }
}

6 具體效果圖:

主頁:

 

接口一:

 

接口二:

 

7 註解說明:

@Api:用在請求的類上,表示對類的說明
    tags="說明該類的作用,UI界面顯示"
    value="UI界面不顯示,無用"

@ApiOperation:用在請求的接口上,解釋說明
    value="對接口的說明"
    notes="接口的描述"

@ApiImplicitParams:用在請求的接口上,表示一組參數說明
    @ApiImplicitParam:用在@ApiImplicitParams註解中,指定一個請求參數的各個方面
        name:參數名
        value:參數的漢字說明、解釋
        required:參數是否必須傳
        paramType:參數放在哪個地方
            · header --> 請求參數的獲取:@RequestHeader
            · query --> 請求參數的獲取:@RequestParam
            · path(用於restful接口)--> 請求參數的獲取:@PathVariable
            · body(不常用)
            · form(不常用)    
        dataType:參數類型,默認String,其它值dataType="int"       
        defaultValue:參數的默認值

@ApiResponses:用在請求的方法上,表示一組響應
    @ApiResponse:用在@ApiResponses中,一般用於表達一個錯誤的響應信息
        code:數字,例如400
        message:信息,例如"請求參數沒填好"
        response:拋出異常的類

@ApiModel:用於響應類上,表示一個返回響應數據的信息
    @ApiModelProperty:用在屬性上,描述響應類的屬性

 

完.

 

 

參考https://www.jianshu.com/p/f30e0c646c63

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章