SpringBoot整合Swagger2及使用

尹瑞星發表於2021-04-13
Spring BootSwagger

簡介

swagger是一個流行的API開發框架，這個框架以“開放API宣告”（OpenAPI Specification，OAS）為基礎， 對整個API的開發週期都提供了相應的解決方案，是一個非常龐大的專案（包括設計、編碼和測試，幾乎支援所有語言）。

springfox大致原理:

springfox的大致原理就是，在專案啟動的過種中，spring上下文在初始化的過程， 框架自動跟據配置載入一些swagger相關的bean到當前的上下文中，並自動掃描系統中可能需要生成api文件那些類， 並生成相應的資訊快取起來。如果專案MVC控制層用的是springMvc那麼會自動掃描所有Controller類，並生成對應的文件描述資料.該資料是json格式，通過路徑：專案地址/ v2/api-docs可以訪問到該資料，然後swaggerUI根據這份資料生成相應的文件描述介面。 因為我們能拿到這份資料，所以我們也可以生成自己的頁面.

SpringBoot整合Swagger2

引入依賴

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

注意：jdk1.8以上才能執行swagger2

編寫配置類配置Swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig{
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.example.yourproject"))//這裡填寫專案package
                .paths(PathSelectors.any())
                .build();
    }//springfox為我們提供了一個Docket（摘要的意思）類，我們需要把它做成一個Bean注入到spring中， 顯然，我們需要一個配置檔案，並通過一種方式（顯然它會是一個註解）告訴程式，這是一個Swagger配置檔案。
  
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2構建RESTful API")
                .description("rest api 文件構建利器")
                .termsOfServiceUrl("https://www.cnblogs.com/yrxing/")
                .contact("xing")
                .version("1.0")
                .build();
    }
  
}//springfox允許我們將資訊組合成一個ApiInfo的類，作為構造引數傳給Docket

在這裡插入圖片描述

訪問：http://localhost:{your_server_port}/swagger-ui.html

Swagger2常用註解使用

在這裡插入圖片描述

@Api()、@ApiOperation()

@RestController
@RequestMapping(value = "/user", produces = APPLICATION_JSON_VALUE) //配置返回值 application/json
@Api(tags = "使用者管理")
public class HelloController {
  
    ArrayList<User> users = new ArrayList<>();
  
    @ApiOperation(value = "獲取使用者列表", notes = "獲取所有使用者資訊")
    @RequestMapping(value = {""}, method = RequestMethod.GET)
    public List<User> hello() {
        users.add(new User("邏輯", "luoji"));
        users.add(new User("葉文傑", "yewenjie"));
        return users;
    }
}

@ApiModel()、@ApiModelProperty()

@ApiModel(description = "使用者",value = "使用者")
public class User {
  
    private String id;
  
  @ApiModelProperty(value = "使用者名稱")//value屬性指明瞭該欄位的含義(描述 Description)
    private String username;
  
   @ApiModelProperty(hidden = true)//此註解可以作用在欄位或者方法上,只要 hidden 屬性為 true ,該欄位或者方法就不會被生成api文件.
    private String password;
  
    private String email;
  
    private Integer age;
  
    private Boolean enabled;
  
}

@ApiParam()

@ApiOperation(value = "獲取使用者詳細資訊", notes = "根據url的id來獲取使用者詳細資訊")
 @RequestMapping(value = "getUser/{id}", method = RequestMethod.GET)
 
 public User getUser(@ApiParam(naeme = "id",value = "使用者id", required = true)  @PathVariable(value = "id") String id) {
     return new User(id, "itguang", "123456");
 }//@ApiParam這個註解,需要注意的是,這個註解方法的引數前面,不能直接用在方法上面.

@ApiImplicitParams()、@ApiImplicitparam()

    ···
  @Api("測試用例1")
  @Controller
  public class swaggerTestUse(){
      @ApiOperation(value = "apiOperationSwaggerTest", notes = "apiOperationSwagger測試")
      @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "id入參", required = true, dataType = "Integer", paramType = "query"),
                        @ApiImplicitParam(name = "brand", value = "brand", required = true, dataType = "BRAND", paramType = "body")
    })
      public void apiOperationSwaggerTest(Integer id, Brand band){
      }
  }

參考連結：

https://www.cnblogs.com/shianliang/p/10472622.html

https://blog.csdn.net/qq_44543508/article/details/105381058

相關文章