天天看點
傳回

spring boot 內建 swagger2

swagger 學習筆記

搭建環境:

  • 1,jdk1.8
  • 2,idea
  • 3,spring-boot-starter-parent版本1.5.6.RELEASE
  • 4，springfox-swagger2 And springfox-swagger-ui 版本2.2.2

1快速環境搭建

建立一個工程，file->new->Porject->Spring Initializr->next-如下圖所示（idea專業版本，社群版可以到git上複制pom檔案）
spring boot 內建 swagger2
pom.xml檔案中添加如下内容(看清楚再複制，此處不是全部内容) 
<properties>
        ...
        <swagger.version>2.2.2</swagger.version>
        ...
    </properties>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
在config目錄中建立swagger的配置檔案swaggerConfig.java 
@EnableSwagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com"))//掃描com路徑下的api文檔
                .paths(PathSelectors.any())//路徑判斷
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("《----我是title-----》")//标題
                .description("《-----我是描述----》：http://www.google.com.hk")//描述
                .termsOfServiceUrl("http://www.google.com.hk")//（不可見）條款位址
                .contact(new Contact("zz","google.com.hk","[email protected]"))//作者資訊
                .version("6.6.6")//版本号
                .build();
    }

}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
建立實體類User，基本字段如下 
@ApiModel(value = "User得實體，----》",reference = "我是參考")
public class User {

    @ApiParam(value = "姓名--------------",required = true)
    private String name;
    //在swagger-ui.html#頁面中如果傳回User，ModelModel Schema頁籤可見
    @ApiModelProperty(value = "id",dataType = "String")
    private String id;
     //在http://localhost:8080/v2/api-docs最後一行的實體可見
    @ApiModelProperty(value = "年齡----------",required = true)
    private Integer age;

    ...此處省略set和get方法
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
在controller包立建立TestController，内容如下 
@Api(value = "API - VehiclesController", description = "使用者接口詳情")
@RestController
@RequestMapping("/test")
public class TestController {

    static Map<String, User> users = Collections.synchronizedMap(new HashMap<String,User>());


    @ApiOperation(value="擷取使用者清單", notes="")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Successful — 請求已完成"),
            @ApiResponse(code = 400, message = "請求中有文法問題，或不能滿足請求"),
            @ApiResponse(code = 401, message = "未授權客戶機通路資料"),
            @ApiResponse(code = 404, message = "伺服器找不到給定的資源；文檔不存在"),
            @ApiResponse(code = 500, message = "伺服器不能完成請求")}
    )
    @RequestMapping(value={""}, method= RequestMethod.GET)
    public List<User> getUserList() {
        List<User> r = new ArrayList<User>(users.values());
        return r;
    }

    ....此處省略n行代碼
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25

浏覽改位址，通路首頁面：http://localhost:8080/swagger-ui.html# 

浏覽改位址，通路sagger專有jsonAPI： http://localhost:8080/v2/api-docs

2常用注釋描述

上半部 

spring boot 內建 swagger2

下半部 

spring boot 內建 swagger2

下下部 

spring boot 內建 swagger2

3全部注釋清單

@Api 

Api 标記可以标記一個Controller類做為swagger 文檔資源，使用方式

屬性名稱 備注
value url的路徑值
tags 如果設定這個值、value的值會被覆寫
description 對api資源的描述
basePath 基本路徑可以不配置
position 如果配置多個Api 想改變顯示的順序位置
produces For example, “application/json, application/xml”
consumes For example, “application/json, application/xml”
protocols Possible values: http, https, ws, wss.
authorizations 進階特性認證時配置
hidden 配置為true 将在文檔中隐藏

@ApiOperation每一個url資源的定義,使用方式

屬性名稱 備注
value url的路徑值
tags 如果設定這個值、value的值會被覆寫
description 對api資源的描述
basePath 基本路徑可以不配置
position 如果配置多個Api 想改變顯示的順序位置
produces For example, “application/json, application/xml”
consumes For example, “application/json, application/xml”
protocols Possible values: http, https, ws, wss.
authorizations 進階特性認證時配置
hidden 配置為true 将在文檔中隐藏
response 傳回的對象
responseContainer 這些對象是有效的 “List”, “Set” or “Map”.，其他無效
httpMethod “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
code http的狀态碼 預設 200
extensions 擴充屬性

@ApiParam标記 

public ResponseEntity createUser(@RequestBody @ApiParam(value = “user”, required = true) User user)

屬性名稱 備注
name 屬性名稱
value 屬性值
defaultValue 預設屬性值
allowableValues 可以不配置
required 是否屬性必填
access 不過多描述
allowMultiple 預設為false
hidden 隐藏該屬性
example 舉例子
@ApiImplicitParam對容器的描述
屬性名稱 備注
name 屬性名稱
value 屬性值
defaultValue 預設值
allowableValues 可以不可配置
required 是否屬性必填
access 不可過多描述
allowMutiple 預設為false
dataType 資料類型
paramType 參數類型

@ApiResponse

屬性名稱 備注
code http的狀态碼
message 描述
response 預設響應類 Void
reference 參考ApiOperation中配置
responseHeaders 參考 ResponseHeader 屬性配置說明
responseContainer 參考ApiOperation中配置
@ResponseHeader(name=”head1”,description=”response head conf”)
屬性名稱 備注
name 響應頭名稱
description 頭描述
response 預設響應類 Void
responseContainer 參考ApiOperation中配置

4文檔編寫規範建議

  • entity的描述

@ApiModel(description = “我是描述”,value = “使用者”) 

對實體的描述

description：在v2/api-docs的實體看到描述， 

value的值在@ApiImplicitParam注解中的dataType可用，

@ApiModelProperty(value = “使用者姓名”,required = true,dataType = “String”) 

private String name; 

對字段的描述

value：1，入參和出參的ModelModel Schema頁籤可見，2，在v2/api-docs的實體字段描述可見 

required：該屬性是否必填寫 

dataType:該字段的資料類型

  • controller的描述

@Api(value = “API”, description = “使用者接口詳情”,tags=”A”) 

對controler的描述

value:通路某個controller的url的根路徑值 

description：對于該controller的的大概描述 

tags:把api接口進行分分組

@ApiOperation(value = “擷取使用者詳細資訊”, notes = “根據url的id來擷取使用者詳細資訊”,httpMethod =”GET”) 

對該方法的描述

value:首頁面中對該接口的描述，位置在接口的最右邊 

notes：點開接口後，第一段描述。 

httpMethod:HTTP請求的動作名，可選值有：”GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”。

@ApiImplicitParam(name = “id”, value = “使用者ID”, required = true, dataType = “String”, paramType = “path”) 

對參數的描述，如果多個參數需要用@ApiImplicitParams對其進行包裹

name:參數名稱 

value：參數的簡短描述 

required:是否必須傳遞的參數 

dataType:參數類型，可以為類名，也可以為基本類型（String，int，Boolean） 

paramType：參數的傳入（請求）類型，可選的值有path, query, body, header or form。（如果在路徑中提取參數用path比如:在／A／{XXX}路徑中得到XXX的值）

@ApiParam(name = “user”, value = “userValue”, required = true) 

對參數元資訊的說明，一般這個注解隻能被使用在JAX-RS 1.x/2.x的綜合環境下，和ApiImplicitParam注解類似

required:該參數是否必填 

value:該參數的簡短介紹

@ApiResponse(code = 200, message = “Successful — 請求已完成”) 

傳回狀态碼的描述,如果有多個可以使用@ApiResponses注解進行包裹

code:伺服器傳回的狀态碼 

message：伺服器傳回狀态碼的簡短說明

sample：header中傳遞token

@ApiImplicitParams({@ApiImplicitParam(name = "TOKEN", value = "Authorization token", required = true, dataType = "string", paramType = "header")})
  • 1

5,注意事項：

  • 路徑參數比如一直傳遞 {id},需要在ApiImplicitParam注解中添加prameType=“path”
  • 版本問題，需要删除m2裡面的jar包，2.2.2的swagger和1.5.6的spring-boot-prent才是絕配，試過很多最新的包，感覺多多少少都有點問題！
  • 入參數和出參數都能用到一個實體類，注意檢查@ApiModel的value屬性

6參考文檔

可能還有其他沒有列出的參考文檔，見諒

https://gumutianqi1.gitbooks.io/specification-doc/content/tools-doc/spring-boot-swagger2-guide.html

http://www.jianshu.com/p/12f4394462d5

http://blog.didispace.com/springbootswagger2/

https://dzone.com/articles/spring-boot-restful-api-documentation-with-swagger

http://www.jianshu.com/p/b0b19368e4a8

附上項目位址

swagger java
上一篇: Spring Boot內建SwaggerSpring Boot內建SwaggerSwagger常用注解
下一篇: 泰山OFFICE技術講座：WORD的縮放比例與顯示略有差異

繼續閱讀