swagger2配置及相關注解說明

• 加入依賴

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

• 配置swagger

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.test.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("測試-練習工程")
                .version("1.0.1")
                .description("測試swagger")
                .build();
    }
}

• 啓用swagger

@EnableSwagger2
@SpringBootApplication
public class XxxApplication {

    public static void main(String[] args) {
        SpringApplication.run(XxxApplication.class, args);
    }
}

• 以下三個方法均爲重寫 RequestHandlerSelectors 中的 3 個方法,使之支持多包掃描,如果重寫了以下3個方法,則需要覆蓋掉SwaggerConfig配置中的RequestHandlerSelectors.basePackage(“cn.test.controller”)改爲有以下方法掃描

    private static Predicate<RequestHandler> basePackage(final String basePackage) {
        return input -> (Boolean) declaringClass(input)
                .transform(SwaggerConfig.handlerPackage(basePackage)).or(true);
    }

    private static Function<Class<?>, Boolean> handlerPackage(final String basePackage) {
        return input -> {
            for (String strPackage : basePackage.split(",")) {
                boolean isMatch = ClassUtils.getPackageName(input).startsWith(strPackage);
                if (isMatch) {
                    return true;
                }
            }
            return false;
        };
    }

    private static Optional<? extends Class<?>> declaringClass(RequestHandler input) {
        return Optional.fromNullable(input.declaringClass());
    }

---

swagger註解

swagger通過註解表明該接口會生成文檔，包括接口名、請求方法、參數、返回信息的等等。

• @Api：修飾整個類，描述Controller的作用
• @ApiOperation：描述一個類的一個方法，或者說一個接口
• @ApiParam：單個參數描述
• @ApiModel：用對象來接收參數
• @ApiProperty：用對象接收參數時，描述對象的一個字段
• @ApiResponse：HTTP響應其中1個描述
• @ApiResponses：HTTP響應整體描述
• @ApiIgnore：使用該註解忽略這個API
• @ApiError ：發生錯誤返回的信息
• @ApiImplicitParam：一個請求參數
• @ApiImplicitParams：多個請求參數
• @Api：修飾整個類，描述Controller的作用

---

1. @Api：用在請求的類上，表示對類的說明
2. tags=“說明該類的作用，可以在UI界面上看到的註解”
3. value=“該參數沒什麼意義，在UI界面上也看到，所以不需要配置”
4. @ApiOperation：用在請求的方法上，說明方法的用途、作用
5. value=“說明方法的用途、作用”
6. notes=“方法的備註說明”
7. @ApiImplicitParams：用在請求的方法上，表示一組參數說明
8. @ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求參數的各個方面
9. name：參數名
10. value：參數的漢字說明、解釋
11. required：參數是否必須傳
12. paramType：參數放在哪個地方
13. header --> 請求參數的獲取：
14. @RequestHeader· query --> 請求參數的獲取：
15. @RequestParam· path（用於restful接口）–> 請求參數的獲取：
16. @PathVariable· body（不常用）
17. form（不常用）
18. dataType：參數類型，默認String，其它值dataType=“Integer”
19. defaultValue：參數的默認值
20. @ApiResponses：用在請求的方法上，表示一組響應
21. @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息
22. code：數字，例如400message：信息，例如"請求參數沒填好"response：拋出異常的類
23. @ApiModel：用於響應類上，表示一個返回響應數據的信息
24. （這種一般用在post創建的時候，使用@RequestBody這樣的場景，
25. 請求參數無法使用@ApiImplicitParam註解進行描述的時候）
26. @ApiModelProperty：用在屬性上，描述響應類的屬性