Swagger使用手冊（自己收藏）

作用：
1. 接口的文檔在線自動生成。
2. 功能測試。

Swagger使用的注解及其說明：

@Api：用在類上，說明該類的作用。

@ApiOperation：注解來給API增加方法說明。

@ApiImplicitParams : 用在方法上包含一組參數說明。

@ApiImplicitParam：用來注解來給方法入參增加說明。
參數：
   ·paramType：指定參數放在哪個地方
      ··header：請求參數放置於Request Header，使用@RequestHeader獲取
      ··query：請求參數放置於請求地址，使用@RequestParam獲取
      ··path：（用於restful接口）-->請求參數的獲取：@PathVariable
      ··body：（不常用）
      ··form（不常用）
   ·name：參數名
   ·dataType：參數類型
   ·required：參數是否必須傳(true | false)
   ·value：說明參數的意思
   ·defaultValue：參數的默認值

@ApiResponses：用於表示一組響應

@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息
      ——code：數字，例如400
      ——message：信息，例如"請求參數異常!"
      ——response：拋出異常的類   

@ApiModel：描述一個Model的信息（一般用在請求參數無法使用@ApiImplicitParam注解進行描述的時候）

@ApiModelProperty：描述一個model的屬性

第一步：導入依賴包(Maven方式)

<!-- swagger2-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-annotations</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

第二步：創建Swagger2配置類

/**
 * Swagger2的接口配置
 * 
 * @author shilinxie
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig
{
    /** 系統基礎配置 */
    @Autowired
    private RuoYiConfig ruoYiConfig;

    /** 是否開啟swagger */
    @Value("${swagger.enabled}")
    private boolean enabled;

    /**
     * 創建API
     */
    @Bean
    public Docket createRestApi()
    {
        return new Docket(DocumentationType.SWAGGER_2)
                // 是否啟用Swagger
                .enable(enabled)
                // 用來創建該API的基本信息，展示在文檔的頁面中（自定義展示的信息）
                .apiInfo(apiInfo())
                // 設置哪些接口暴露給Swagger展示
                .select()
                // 掃描所有有注解的api，用這種方式更靈活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 掃描指定包中的swagger注解
                //.apis(RequestHandlerSelectors.basePackage("com.ruoyi.project.tool.swagger"))
                // 掃描所有 .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo()
    {
        // 用ApiInfoBuilder進行定制
        return new ApiInfoBuilder()
                // 設置標題
                .title("標題：XXXXXX")
                // 描述
                .description("描述：用於管理集團旗下公司的人員信息,具體包括XXX,XXX模塊...")
                // 作者信息
                .contact(new Contact(ruoYiConfig.getName(), null, null))
                // 版本
                .version("版本號:" + ruoYiConfig.getVersion())
                .build();
    }
}

第三步：使用Swagger提供的注解

/**
 * @Auther: shilinxie
 * @Description:Swagger 示例
 */
@RestController
@RequestMapping("/oss")
@Api(value = "Swagger 示例",description = "用來演示Swagger的一些注解")
public class TestController {


    @ApiOperation(value="修改用戶密碼", notes="根據用戶id修改密碼")
    @ApiImplicitParams({
        @ApiImplicitParam(paramType="query", name = "userId", value = "用戶ID", required = true, dataType = "Integer"),
        @ApiImplicitParam(paramType="query", name = "password", value = "舊密碼", required = true, dataType = "String"),
        @ApiImplicitParam(paramType="query", name = "newPassword", value = "新密碼", required = true, dataType = "String")
    })
    @RequestMapping("/updatePassword")
    public String updatePassword(@RequestParam(value="userId") Integer userId, @RequestParam(value="password") String password, 
            @RequestParam(value="newPassword") String newPassword){
         if(userId <= 0 || userId > 2){
             return "未知的用戶";
         }
         if(StringUtils.isEmpty(password) || StringUtils.isEmpty(newPassword)){
             return "密碼不能為空";
         }
         if(password.equals(newPassword)){
             return "新舊密碼不能相同";
         }
         return "密碼修改成功!";
     }
}