swagger配置

Swagger作用：

自動生成javaAPI，避免開發過程中接口文檔更新不及時。

Swagger 一.導入依賴：

導入依賴

<!--swagger包-->
<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>
<!--swagger包結束-->

 

 

 

 

 

 

 

Swagger 二.Swagger首頁的配置：

創建一個SwaggerConfig類，通過@Configuration托管給spring，然后通過@EnableSwagger2 注解開啟Swagger，Config類大部分都是固定的，沒什么改變的需要：

代碼：

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

/**
 * @author 趙振宇
 * @date 2019/10/29 0029
 * @time 14:51
 * @desc Swagger配置類，該類里面的應該是固定的，主要用來設置文檔的主題信息，比如文檔的大標題，副標題，公司名
 * 等
 */
@Configuration//托管spring
@EnableSwagger2//開啟swagger功能
public class SwaggerConfig {
    /**
     * 創建API應用
     * apiInfo() 增加API相關信息
     * 通過select()函數返回一個ApiSelectorBuilder實例,用來控制哪些接口暴露給Swagger來展現，
     * 本例采用指定掃描的包路徑來定義指定要建立API的目錄。
     *
     * @return
     */
    @Bean
    public Docket createRestApi(){
        //版本類型是swagger2
        return new Docket(DocumentationType.SWAGGER_2)
                //通過調用自定義方法apiInfo，獲得文檔的主要信息
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zy100.controller"))//掃描該包下面的API注解
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 創建該API的基本信息（這些基本信息會展現在文檔頁面中）
     * 訪問地址：http://項目實際地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("使用Swagger2 構建RESTful APIS - zy") //接口管理文檔首頁顯示
                .description("zy - Swagger使用演示")//API的描述
                .termsOfServiceUrl("www.footmark.top")//網站url等
                .version("1.0")
                .build();
    }
}

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Swagger 三.Swagger的Controller示例

在需要生成接口文檔的Controller中加上@API注解，類中需要生成接口的方法上加上@ApiOperation注解：

代碼：

package com.zy100.controller;

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.Date;
import java.util.HashMap;
import java.util.Map;

/**
 * @author 趙振宇
 * @date 2019/10/29 0029
 * @time 15:00
 * @desc 配合swagger創建一個Controller，演示方便不再創建service層
 */
@RestController
@Api("用戶模塊API文檔")//注解api說明該類需要生成api文檔
public class UserController {
    /**
     * 該類中
     * @param map 類似於一個user對象
     * key就是對象的屬性
     * value就是對象的屬性值
     *   ------------------------
     * 屬性 id name birthday
     * @return
     *
     */
    //正常業務整添加是對象，前台傳JSON對象，在此使用map代替
    @PostMapping("/user")//如果使用swagger自動生成接口文檔，一定要加上請求類型，不然會導致swagger把所有請求都會生成一下
    @ApiOperation("添加用戶")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "map",//參數名字
                    value = "這是一個添加的對象",//參數的描述
                    required = true,//是否必須傳參數，true是
                    paramType = "body")//參數類型 body代表json
    })
    public Map add(@RequestBody Map map){
        return map;
    }
    //根據id刪除數據。
    @DeleteMapping("/user/{id}")
    @ApiOperation("刪除用戶")//API中說明的該類的作用
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",//參數名字
                    value = "用戶id",//參數的描述
                    required = true,//是否必須傳參數，true是
                    paramType = "path",//參數類型 path代表路徑參數
                    dataType = "int")//參數類型 int
    })
    public String deltete(@PathVariable int id){
        return "{code:200,msg:刪除"+id+"成功}";
    }
    //根據傳入的對象信息進行更新
    @PutMapping("/user")
    @ApiOperation("更新用戶")//API中說明的該類的作用
    @ApiImplicitParams({
            @ApiImplicitParam(name = "map",//參數名字
                    value = "更新的用戶",//參數的描述
                    required = true,//是否必須傳參數，true是
                    paramType = "body",//參數類型 body
                    dataType = "map")//參數類型 int
    })
    public Map update(@RequestBody Map map){
        return map;
    }
    @GetMapping("/user/{id}")
    @ApiOperation("查詢永不用戶")//API中說明的該類的作用
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",//參數名字
                    value = "查詢的用戶id",//參數的描述
                    required = true,//是否必須傳參數，true是
                    paramType = "path",//參數類型 body
                    dataType = "int")//參數類型 int
    })
    public Map getOne(@PathVariable int id){
        Map<String,Object> map = new HashMap<>();
        map.put("id",id);
        map.put("name","張三");
        map.put("birthday",new Date());
        return map;
    }
}

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Swagger 四.測試

運行啟動類主方法，訪問：http://localhost:8080/swagger-ui.html 

可以看到效果