一前言

這篇文章主要是帶大家入門下如何使用OpenAPI, 筆者在github上找到對應得swagger項目都沒找到javase得人門文章，看了下是基於JAX-RS，吐血了；

二什么是 OpenAPI，

OpenAPI 是一種基於Resful 風格對 API進行格式化描述的一種規范；允許你描述你整個項目的API，簡單的講就是一種接口文檔生成的規范；包括如下幾點：

端點描述（如 GET /user , Post /user）;
操作的參數，入輸入參數，輸出參數；
認證信息
聯系信息，許可條款，聲明等

三什么是 Swagger

Swagger 由多個組件組成，它是一個開源的構建工具，其作用就是以 OpenAPI 為規范基准，能夠幫助開發人員設計，構建文檔，測試接口，文檔規范化，和消費掉Restful API；說白了就是 OpenAPI 的實現，能夠生成接口文檔，以后不用自己手寫了！！！我們可以看下其主要組件如下：

在這里插入圖片描述

Swagger Editor 是一個編輯工具，可以編輯描述API；
Swagger UI 能讓OpenAPI呈現出規范的可交互的API文檔，以供他人查閱；
Swagger Codegen 基於OpenAPI規范能夠生成客戶端類庫，服務端文檔和存根，並且支持多語言，支持使用Docker,jar等方式運行構建；

更多組件詳細看官網：swagger doc，看了官網的ylm格式基本結構暈，一堆黑的，客戶體驗非常不友好吐槽一下！看了github是基於JAX-RS 應用，不是很懂，再吐槽一下；

在這里插入圖片描述

四 API生成

4.1 相關注釋

注釋	說明
@Api	標記類上，表明是資源
@ApiImplicitParam	表示API操作中的單個參數。
@ApiImplicitParams	允許多個參數列表
@ApiModel	針對實體model提供額外信息
@ApiModelProperty	添加操作數據或者model屬性
@ApiOperation	描述HTTP方法，通常針對特定的路徑
@ApiParam	對於操作添加額外的信息
@ApiResponse	描述一個操作的響應
@ApiResponses	允許多個參數列表，描述響應對象
@Authorization	使用在類上或者方法上，表示授權信息
@AuthorizationScope	描述 OAuth2 的授權作用域
@ResponseHeader	代表響應頭的部分信息

4.2 pom.xml

<dependencies>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.22</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.22</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.16.18</version>
            <optional>true</optional>
        </dependency>
    </dependencies>

4.3 swagger配置

主要是配置一些項目得基本信息，注解路徑，項目主要聯系人等；比較重要是@EnableSwagger2表示開啟Swagger；

/**
 * @Author lsc
 * <p> swagger 配置 </p>
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        // 構建文檔
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        // 文檔信息
        Docket build = docket.apiInfo(apiInfo())
                // 查詢
                .select()
                // 注解包的路徑
                .apis(RequestHandlerSelectors.basePackage("com.zszxz.swagger.controller"))
                // 任何路徑
                .paths(PathSelectors.any())
                .build();
        return build;

    }
    /* *
     * @Author lsc
     * <p> 文檔信息</p>
     * @Param []
     * @Return springfox.documentation.service.ApiInfo
     */
    private ApiInfo apiInfo() {
        // 文檔對象構建器
        ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
        // 文檔標題
        ApiInfo apiInfo = apiInfoBuilder.title("知識追尋者（公眾號） API doc")
                // 描述信息
                .description("知識追尋者第一次操作OpenAPI！！！！！")
                // 版本號
                .version("v1")
                // 聯系人
                .contact(new Contact("知識追尋者", "https://blog.csdn.net/youku1327", "lsc50534314@gmail.com"))
                // 聲明許可
                .license("知識追尋者許可")
                // 許可路徑，這邊是我的github
                .licenseUrl("https://github.com/zszxz")
                .build();

        return apiInfo;

    }
}

4.4 實體

/**
 * @Author lsc
 * <p> </p>
 */
@Data
@ApiModel(description = "用戶知識追尋者實體")
public class ZSZXZ {

    @ApiModelProperty(value = "姓名",dataType = "String")
    private String name;
    @ApiModelProperty(value = "郵件",dataType = "String")
    private String email;
    @ApiModelProperty(value = "愛好",dataType = "String")
    private String hobby;
}

4.5 controller

/**
 * @Author lsc
 * <p> </p>
 */
@RestController
// 資源信息
@Api(value = "知識追尋者文檔API")
public class SwaggerController {

    // 方法注釋
    @ApiOperation(value = "獲取用戶")
    // 響應信息
    @ApiResponse(code = 200,message = "獲取用戶列表成功")
    @GetMapping("zszxz")
    public ResponseEntity getUser(){
        ZSZXZ zszxz = new ZSZXZ();
        zszxz.setName("知識追尋者");
        zszxz.setHobby("愛睡覺");
        zszxz.setEmail("不告訴你");
        return ResponseEntity.ok(zszxz);
    }

    // 方法注釋
    @ApiOperation(value = "跟據用戶編號獲取用戶")
    // 響應信息
    @ApiResponses({@ApiResponse(code = 200,message = "獲取用戶列表成功")
                    ,@ApiResponse(code = 204,message = "沒有內容")})
    // 參數信息
    @ApiImplicitParam(name = "id", value = "用戶編號", dataType = "ZSZXZ",required = true, paramType = "path")
    @GetMapping("zszxz/{id}")
    public ResponseEntity getUserById(@PathVariable Long id){
        ZSZXZ zszxz = new ZSZXZ();
        zszxz.setName("知識追尋者");
        zszxz.setHobby("愛睡覺");
        zszxz.setEmail("不告訴你");
        return ResponseEntity.ok(zszxz);
    }

    @PostMapping("zszxz")
    // 響應信息
    @ApiResponse(code = 201,message = "添加用戶列表成功")
    // 方法信息
    @ApiOperation(value = "添加用戶")
    public ResponseEntity addUser(@RequestBody ZSZXZ zszxz){

        System.out.println("save the user:"+zszxz);
        return ResponseEntity.ok("success save the user");
    }

    // 響應信息
    @ApiResponse(code = 200,message = "修改用戶成功")
    @ApiOperation(value = "修改用戶",notes = "修改用戶")
    @PutMapping("zszxz/{id}")
    // 參數信息 多個參數使用注釋中得內容, @RequestBody 修斯參數沒必要寫
    /*@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "用戶編號", dataType = "Long",required = true,paramType = "path")
    ,@ApiImplicitParam(name = "user", value = "用戶", dataType = "ZSZXZ",required = true, paramType = "json")})*/
    @ApiImplicitParam(name = "id", value = "用戶編號", dataType = "Long",required = true,paramType = "path")
    public ResponseEntity updateUser(@PathVariable Long id ,@RequestBody ZSZXZ zszxz){

        System.out.println("update the user:"+zszxz);
        return ResponseEntity.ok("success update the user,the number is :"+id);
    }


    // 響應信息
    @ApiResponses({@ApiResponse(code = 200,message = "刪除用戶成功")
            ,@ApiResponse(code = 401,message = "沒有權限")
            })
    @ApiOperation(value = "刪除用戶")
    @DeleteMapping("zszxz/{id}")
    @ApiImplicitParam(name = "id", value = "用戶編號", dataType = "Long",required = true,paramType = "path")
    public ResponseEntity updateUser(@PathVariable Long id ){
        System.out.println("delete the user :"+id);
        return ResponseEntity.ok("delete the user :"+id);
    }



}