在 Spring Boot 使用 Swagger2

時間 2019-11-16

標籤 spring boot 使用 swagger2 swagger 欄目 Spring 简体版

原文原文鏈接

在 Spring Boot 使用 Swagger2

世界上最流行的API工具
Swagger是世界上最大的OpenAPI規範（OAS）API開發工具框架，html

在整個API生命週期中實現開發，從設計和文檔到測試和部署。java

1.什麼是 Swagger2

Swagger 是一個功能強大且易於使用的API開發人員工具套件，適用於團隊和我的，支持從整個API生命週期（從設計和文檔到測試和部署）的開發。Swagger 用於更好地實現和可視化規範中定義的API。spring

2.爲何使用 Swagger2

設計是API開發的基礎。Swagger2 使API設計變得垂手可得，爲開發人員，架構師和產品全部者提供了易於使用的工具。
Swagger2 提供了快速原型設計和構建API功能的工具。
Swagger2 提供了一系列用於生成、可視化和維護API文檔的解決方案。
Swagger2 工具使您能夠輕鬆快速地建立，管理和執行API測試。

3.如何使用 Swagger2

3.1配置 Swagger2

1.向 pom.xml 添加 Swagger2 依賴api

<!-- swagger2依賴 -->
        <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.7.0</version>
        </dependency>

2.建立 Swagger2 的配置類微信

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 配置是否開啓Swagger2
     */
    @Value("${swagger.enable}")
    private boolean enableSwagger;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enableSwagger)    // enable(true)表示開啓Swagger
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .title("開發框架 Demo")
                        .description("用戶、商戶信息表的增、刪、改、查接口。")
                        .version("1.0")
                        .contact("lxiao")
                        .build());
    }
}

@Configuration註解用於使spring加載配置類。@EnableSwagger2用於開啓 Swagger2.架構

在 Swagger2 的配置類中，經過建立createRestApi()函數建立 Docket 的Bean。app

enable()用來開啓和禁用 Swagger 。若參數爲 true 則開啓 Swagger ，參數爲 false 則禁用 Swagger 。能夠在 application 配置來控制本地開發環境開啓 Swagger，測試環境和生產環境禁用 Swagger。框架

select()函數返回一個ApiSelectorBuilder實例用來控制哪些接口暴露給 Swagger 來展示函數

apis()選擇那些接口用於 Swagger。示例中將com.example.demo.controller包下的接口用於 Swagger。工具

apiInfo()函數用來建立 API 的基本信息。

配置完成 SwaggerConfig 後啓動項目，訪問 http://localhost:8080/swagger-ui.html 。

這就是 swagger-ui 的界面，在 swagger-ui 能夠看到剛纔配置的 API 信息。

3.2 Swagger2 註解介紹

1.Swagger2 經常使用註解，添加文檔內容。

@Api(value="用戶controller",tags={"用戶操做接口"})
@RestController
@RequestMapping("api/user")
public class UserController {

    @RequestMapping(value = "/" , method = RequestMethod.POST)
    @ApiOperation(value = "添加用戶的接口")
    public Object add(@RequestBody User user){
        //...具體接口實現
    }
}

@Api(value = "message" , tags = {"message"})用於類，表示標識這個類是swagger的資源。

@ApiOperation(value = "message")用於方法，表示一個http請求的操做。

啓動項目查看效果：

@ApiModel(value="用戶對象",description="用戶對象user")
public class User {
    
    @ApiModelProperty(value = "用戶ID")
    private String id;
    
    @ApiModelProperty(value = "用戶名")
    private String userName;
    
    @ApiModelProperty(value = "用戶密碼")
    private String userPassword;
}

@ApiModel(value = "message" , description = "message")用於類表示對類進行說明，用於參數用實體類接收

@ApiModelProperty(value = "message")用於方法，字段。表示對model屬性的說明或者數據操做更改。

啓動項目查看效果：

@RequestMapping(value = "/" , method = RequestMethod.GET)
    @ApiOperation(value = "查詢用戶的接口")
    public Object query(@ApiParam(name="id",value="用戶id",required=true) String id){
        //...具體接口實現
    }

@ApiParam(name = "message" , value = "message" , required = true)用於方法，參數，字段說明，表示對參數的添加元數據（說明或是否必填等）

啓動項目查看效果：