一前言

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

二什麼是 OpenAPI，

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

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

三什麼是 Swagger

Swagger 由多個組件組成，它是一個開源的構建工具，其做用就是以 OpenAPI 爲規範基準，可以幫助開發人員設計，構建文檔，測試接口，文檔規範化，和消費掉Restful API；說白了就是 OpenAPI 的實現，可以生成接口文檔，之後不用本身手寫了！！！咱們能夠看下其主要組件以下：github

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

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

四 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；spring

/**
 * @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);
    }



}

4.6 生成結果

默認路徑：localhost:8080/swagger-ui.html#/ json

4.7 查看實體

4.8 查詢接口測試

打開測試查詢接口：測試結果： api

4.9 添加用戶測試

因爲註解時偷懶沒加example，因此這邊測試要本身動手寫測試數據； app

測試結果以下spring-boot

五結語

修改和刪除就不測試了，很簡單，讀者自行測試；基本經常使用得註解使用都過了，其他得讀者自行研究，整體來講使用仍是很愉快，默認文檔路徑是能夠修改得，讀者自行搜索；源碼請看做者博客專欄說明；

springboot-使用OpenAPI以後我再也沒有寫過接口文檔

一 前言

二 什麼是 OpenAPI，

三 什麼是 Swagger