一、引入依賴:

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

注意了注意了知識點! 

版本一定要2.5.0以及以上版本! 網上博文大多數引的2.2.2版本的, 這個版本在demo中沒有問題, 但是開發中你肯定會引別的外掛.

2.2.2版本的與feign有衝突! 會報bean建立載入異常!  這是個坑不想網友們再遇到同樣的錯誤.

--------------------------------------------------------------------------------------------------------------------------------------------------------------------

二、Swagger2配置檔案類:

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;

/**
* @ClassName: swagger2配置
* @Description: TODO
* @author 劉圈圈
* @date 2018年7月5日
*/

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("io.sr.modules.tra.app"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("旅遊用車  APIs")
                .description("--------------------------------")
                .termsOfServiceUrl("https://blog.csdn.net/ityqing")
                .contact("劉圈圈")
                .version("0.1.1")
                .build();
    }

}
 

這個類要和啟動類放在同一個目錄下, 

用@Configuration註解該類，等價於XML中配置beans；用@Bean標註方法等價於XML中配置bean。

Application.class 加上註解@EnableSwagger2 表示開啟Swagger,也可以在配置檔案上加@EnableSwagger2

-----------------------------------------------------------------------------------------------------------------------------------------------------------------------

我的包結構:

.apis(RequestHandlerSelectors.basePackage("io.sr.modules.tra.app"))  : 是設定掃描的包路徑

io.sr.modules.tra.app 它是模糊匹配的,所以我們在建立包還有URL時要避免這種格式

result介面:

這一步不是必要的, 只要swagger掃描到@RestController註解的類就會按預設配置生成介面文件

三、controller程式碼:

@RestController
@RequestMapping("/user")
@Api(value = "Shop")
public class SpringBootController {
 
    @ApiOperation(value = "獲取helloWorld", notes = "簡單SpringMVC請求")
    @RequestMapping("/")
    String home() {
        return "HELLO WORLD";
    }
 
    @ApiOperation(value = "獲得A+B", notes = "根據url的classNo和url的studentName獲得請求引數的字串相加，RestFul風格的請求")
    @ApiImplicitParams({@ApiImplicitParam(name = "classNo", value = "班級編號", required = true, dataType = "String"),
    })
    @RequestMapping(value = "/class/{classNo}/to/{studentName}", method = RequestMethod.GET)
    String world(@PathVariable("classNo") String classNo, @PathVariable("studentName") String studentName) {
        return classNo + "  " + studentName;
    }
 
 
}

四、Swagger註解

swagger通過註解表明該介面會生成文件，包括介面名、請求方法、引數、返回資訊的等等。

• @Api：修飾整個類，描述Controller的作用
• @ApiOperation：描述一個類的一個方法，或者說一個介面
• @ApiParam：單個引數描述
• @ApiModel：用物件來接收引數
• @ApiProperty：用物件接收引數時，描述物件的一個欄位
• @ApiResponse：HTTP響應其中1個描述
• @ApiResponses：HTTP響應整體描述
• @ApiIgnore：使用該註解忽略這個API
• @ApiError ：發生錯誤返回的資訊
• @ApiImplicitParam：一個請求引數
• @ApiImplicitParams：多個請求引數

@RequestMapping此註解的推薦配置 
value 
method 
produces

示例：

    @ApiOperation("資訊軟刪除")
    @ApiResponses({ @ApiResponse(code = CommonStatus.OK, message = "操作成功"),
            @ApiResponse(code = CommonStatus.EXCEPTION, message = "伺服器內部異常"),
            @ApiResponse(code = CommonStatus.FORBIDDEN, message = "許可權不足") })
    @ApiImplicitParams({ @ApiImplicitParam(paramType = "query", dataType = "Long", name = "id", value = "資訊id", required = true) })
    @RequestMapping(value = "/remove.json", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public RestfulProtocol remove(Long id) {

    @ApiModelProperty(value = "標題")
    private String  title;

@ApiImplicitParam

paramType 示例詳解

path

 @RequestMapping(value = "/findById1/{id}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)

 @PathVariable(name = "id") Long id

body

  @ApiImplicitParams({ @ApiImplicitParam(paramType = "body", dataType = "MessageParam", name = "param", value = "資訊引數", required = true) })
  @RequestMapping(value = "/findById3", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_JSON_VALUE)

  @RequestBody MessageParam param

  提交的引數是這個物件的一個json，然後會自動解析到對應的欄位上去，也可以通過流的形式接收當前的請求資料，但是這個和上面的接收方式僅能使用一個（用@RequestBody之後流就會關閉了）

header

  @ApiImplicitParams({ @ApiImplicitParam(paramType = "header", dataType = "Long", name = "id", value = "資訊id", required = true) }) 

   String idstr = request.getHeader("id");
        if (StringUtils.isNumeric(idstr)) {
            id = Long.parseLong(idstr);
        }

Form

@ApiImplicitParams({ @ApiImplicitParam(paramType = "form", dataType = "Long", name = "id", value = "資訊id", required = true) })
 @RequestMapping(value = "/findById5", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)