轉自：https://blog.csdn.net/xxoo00xx00/article/details/77163399

搭建環境:

• 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檔案）

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

2常用註釋描述

上半部 

下半部 

下下部 

3全部註釋列表

@Api 
Api 標記可以標記一個Controller類做為swagger 文件資源，使用方式

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

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

@ApiImplicitParam對容器的描述

@ApiResponse

@ResponseHeader(name=”head1”,description=”response head conf”)

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參考文件

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

附上專案地址