欧美bbbwbbbw肥妇,免费乱码人妻系列日韩,一级黄片

詳解Swagger接口文檔和常用注解的使用

 更新時間：2022年08月08日 09:42:10   作者：張維鵬  
Swagger是一款遵循?Restful?風格的接口文檔開發(fā)神器，支持基于?API?自動生成接口文檔。本文將為大家講講Swagger接口文檔和常用注解的使用方法，需要的可以參考一下

Swagger是一款遵循 Restful 風格的接口文檔開發(fā)神器，支持基于 API 自動生成接口文檔，接口文檔始終與 API 保持同步，不再需要手動編寫接口文檔，并且采用全注解的方式，開發(fā)簡單，代碼侵入性低，對服務端開發(fā)的程序員來說非常方便，可以節(jié)約大量寫接口文檔的時間。除此之外，Swagger 生成的文檔還支持在線測試，參數(shù)和格式都定好了，直接在界面上輸入?yún)?shù)對應的值即可在線測試接口。

一、Spring整合Swagger

（1）在 pom.xml 文件中添加 Swagger 的 maven 依賴：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>

（2）編寫Swagger自定義配置類：

/** 
* 類說明 :自定義swagger配置信息
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    @Bean
     public Docket creatApi(){
     return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select() //選擇哪些路徑和api會生成document
      .apis(RequestHandlerSelectors.basePackage("com.zwp.controller"))//controller路徑
      //.apis(RequestHandlerSelectors.any())   //對所有api進行監(jiān)控
      .paths(PathSelectors.any())  //對所有路徑進行監(jiān)控
      .build();
     }
    
    //接口文檔的一些基本信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springmvc+swagger整合")//文檔主標題
                .description("test接口文檔")//文檔描述
                .version("1.0.0")//API的版本
                .termsOfServiceUrl("###")
                .license("LICENSE")
                .licenseUrl("###")
                .build();
    }
}

在 springmvc.xml 文件中配置創(chuàng)建對象：

<!-- 使用注解驅動：自動配置處理器映射器與處理器適配器 -->
<mvc:annotation-driven />
<!-- 注解方式：自動掃描該包 -->
<context:component-scan base-package="com.zwp.config" />

（3）在 springmvc.xml 中過濾掉 swagger-ui 的靜態(tài)資源文件：

<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />

（4）在controller類添加swagger的注解：

//在類上面加@Api注解，表明該controller類需要被swagger自動生成文檔
@Api(tags="UserController",description="user的控制層")
@Controller
@RequestMapping("/user")
public class UserController {
    
    @Autowired
    private UserService userService;
 
     //在方法上面添加@ApiOperation注解，表明該方法需要被swagger自動生成文檔
    @ApiOperation(httpMethod="GET",value="接口標題:獲取用戶信息",notes="接口的notes說明：需要user的id")
    @RequestMapping(value="/getUserById/{userId}",method=RequestMethod.GET)
    public @ResponseBody User getUserById(@PathVariable Integer userId){
        return userService.getUserById(userId);
    }
    
}

（5）部署工程，訪問路徑：

格式：http://服務器ip:端口/項目名稱//swagger-ui.html

例子：http://localhost:8080/ssm/swagger-ui.html

見到上面頁面，表示整合成功。

二、swagger常用注解說明

注解說明
@Api修飾controller類，標識這個類是swagger的資源 
@ApiOperation修飾controller的方法，表示一個http請求的操作
@ApiParam修飾方法的參數(shù)，用于添加參數(shù)說明與是否必填等元數(shù)據(jù)
@ApiModel修飾對象類，表示對對象類進行說明，用于參數(shù)用實體類接收的場景
@ApiModelProperty修飾對象類中的屬性，對屬性進行說明
@ApiIgnore()修飾類、方法、參數(shù)等，表示不顯示在swagger文檔中
@ApiImplicitParam用于方法，表示單獨的請求參數(shù)
@ApiImplicitParams用于方法，包含多個 @ApiImplicitParam

 1、@Api的使用說明

修飾controller類，標識這個類是swagger的資源，屬性說明：

tags：類的說明，但是tags如果有多個值，會生成多個list

value：也是類的說明，可以使用tags替代

@Api(value="用戶controller",tags={"用戶操作接口"})
@RestController
public class UserController {
 
}

 效果圖： 

2、@ApiOperation的使用說明

修飾controller的方法，表示一個http請求的操作，屬性說明：

value：用于方法描述 

notes：用于提示內容 

tags：可以重新分組，視情況而用）

3、@ApiParam的使用說明

修飾方法的參數(shù)，用于添加參數(shù)說明與是否必填等元數(shù)據(jù)，屬性說明：

name：參數(shù)名 

value：參數(shù)說明 

required：是否必填

@Api(value="用戶controller",tags={"用戶操作接口"})
@RestController
public class UserController {
     @ApiOperation(value="獲取用戶信息",tags={"獲取用戶信息copy"},notes="注意問題點")
     @GetMapping("/getUserInfo")
     public User getUserInfo(@ApiParam(name="id",value="用戶id",required=true) Long id,@ApiParam(name="username",value="用戶名") String username) {
     // userService可忽略，是業(yè)務邏輯
      User user = userService.getUserInfo();
 
      return user;
  }
}

效果圖： 

4、@ApiModel的使用說明

修飾對象類，表示對對象類進行說明，用于參數(shù)用實體類接收的場景，屬性說明：

value：表示對象名，可省略

description：描述，可省略

5、@ApiModelProperty的使用說明

修飾對象類中的屬性，對屬性進行說明，屬性說明：

  • value：字段說明
  • name：重寫屬性名字
  • dataType：重寫屬性類型
  • required：是否必填
  • example：舉例說明
  • hidden：是否隱藏
@ApiModel(value="user對象",description="用戶對象user")
public class User implements Serializable{
    private static final long serialVersionUID = 1L;
     @ApiModelProperty(value="用戶名",name="username",example="xingguo")
     private String username;
     @ApiModelProperty(value="狀態(tài)",name="state",required=true)
      private Integer state;
      private String password;
      private String nickName;
      private Integer isDeleted;
 
      @ApiModelProperty(value="id數(shù)組",hidden=true)
      private String[] ids;
      private List<String> idList;
}
  @ApiOperation("更改用戶信息")
  @PostMapping("/updateUserInfo")
  public int updateUserInfo(@RequestBody @ApiParam(name="用戶對象",value="傳入json格式",required=true) User user){
 
     int num = userService.updateUserInfo(user);
     return num;
  }

效果圖： 

6、@ApiIgnore的使用說明

修飾類、方法、參數(shù)等，表示不顯示在swagger文檔中，比較簡單, 這里不做舉例

7、@ApiImplicitParam的使用說明

用于方法，表示單獨的請求參數(shù)

8、@ApiImplicitParams的使用說明

用于方法，包含多個 @ApiImplicitParam，屬性說明：

  • name：參數(shù)ming 
  • value：參數(shù)說明 
  • dataType：數(shù)據(jù)類型 
  • paramType：參數(shù)類型 
  • example：舉例說明
  @ApiOperation("查詢測試")
  @GetMapping("select")
  //@ApiImplicitParam(name="name",value="用戶名",dataType="String", paramType = "query")
  @ApiImplicitParams({
  @ApiImplicitParam(name="name",value="用戶名",dataType="string", paramType = "query",example="xingguo"),
  @ApiImplicitParam(name="id",value="用戶id",dataType="long", paramType = "query")})
  public void select(){
 
  }

效果圖：

9、@ApiResponses與@ApiResponse使用說明

這兩個注解都表示對響應結果進行說明

10、@RequestMapping注解的推薦配置

value、method、produces

示例：

    @ApiOperation("信息軟刪除")
    @ApiResponses({ @ApiResponse(code = CommonStatus.OK, message = "操作成功"),
            @ApiResponse(code = CommonStatus.EXCEPTION, message = "服務器內部異常"),
            @ApiResponse(code = CommonStatus.FORBIDDEN, message = "權限不足") })
    @ApiImplicitParams({ @ApiImplicitParam(paramType = "query", dataType = "Long", name = "id", value = "信息id", required = true) })
    @RequestMapping(value = "/remove.json", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public RestfulProtocol remove(Long id) {

以上就是詳解Swagger接口文檔和常用注解的使用的詳細內容，更多關于Swagger接口文檔 注解的資料請關注腳本之家其它相關文章！

相關文章

  • Java使用split截取字符串過程解析

    Java使用split截取字符串過程解析

    這篇文章主要介紹了Java使用split截取字符串過程解析,文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值,需要的朋友可以參考下
    2020-02-02
  • 獲取JPEGImageEncoder和JPEGCode這兩個類的方法

    獲取JPEGImageEncoder和JPEGCode這兩個類的方法

    下面小編就為大家?guī)硪黄@取JPEGImageEncoder和JPEGCode這兩個類的方法。小編覺得挺不錯的，現(xiàn)在就分享給大家，也給大家做個參考。一起跟隨小編過來看看吧
    2017-07-07
  • Java中字符串去重的特性介紹

    Java中字符串去重的特性介紹

    這篇文章主要介紹了Java中字符串去重的特性,是Java8中引入的一個新特性,至于是否真的用起來順手就見仁見智了...需要的朋友可以參考下
    2015-07-07
  • Java Unsafe學習筆記分享

    Java Unsafe學習筆記分享

    今天小編就為大家分享一篇Java Unsafe學習筆記，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教
    2021-11-11
  • Jmeter使用接口傳遞數(shù)據(jù)過程圖解

    Jmeter使用接口傳遞數(shù)據(jù)過程圖解

    這篇文章主要介紹了Jmeter使用接口傳遞數(shù)據(jù)過程圖解,文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值,需要的朋友可以參考下
    2020-05-05
  • Spring中使用騰訊云發(fā)送短信驗證碼的實現(xiàn)示例

    Spring中使用騰訊云發(fā)送短信驗證碼的實現(xiàn)示例

    本文主要介紹了Spring?中?使用騰訊云發(fā)送短信驗證碼，文中通過示例代碼介紹的非常詳細，具有一定的參考價值，感興趣的小伙伴們可以參考一下
    2022-03-03
  • springboot+thymeleaf+druid+mybatis 多模塊實現(xiàn)用戶登錄功能

    springboot+thymeleaf+druid+mybatis 多模塊實現(xiàn)用戶登錄功能

    這篇文章主要介紹了springboot+thymeleaf+druid+mybatis 多模塊實現(xiàn)用戶登錄功能,本文通過示例代碼圖文相結合給大家介紹的非常詳細，對大家的學習或工作具有一定的參考借鑒價值，需要的朋友可以參考下
    2020-07-07
  • 詳解java中的PropertyChangeSupport與PropertyChangeListener

    詳解java中的PropertyChangeSupport與PropertyChangeListener

    這篇文章主要介紹了詳解java中的PropertyChangeSupport與PropertyChangeListener的相關資料,需要的朋友可以參考下
    2017-09-09
  • spring cloud 使用Zuul 實現(xiàn)API網(wǎng)關服務問題

    spring cloud 使用Zuul 實現(xiàn)API網(wǎng)關服務問題

    這篇文章主要介紹了spring cloud 使用Zuul 實現(xiàn)API網(wǎng)關服務問題，非常不錯，具有一定的參考借鑒價值，需要的朋友可以參考下
    2018-05-05
  • Spring將一個的類配置成Bean的方式詳解

    Spring將一個的類配置成Bean的方式詳解

    這篇文章主要介紹了Spring將一個的類配置成Bean的方式，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習吧
    2023-03-03

最新評論