App下載

SpringBoot項(xiàng)目中整合swagger2的詳細(xì)步驟解析

猿友 2021-08-05 13:48:42 瀏覽數(shù) (2534)
反饋

簡介

swagger是一個(gè)流行的API開發(fā)框架,這個(gè)框架以“開放API聲明”(OpenAPI Specification,OAS)為基礎(chǔ), 對(duì)整個(gè)API的開發(fā)周期都提供了相應(yīng)的解決方案,是一個(gè)非常龐大的項(xiàng)目(包括設(shè)計(jì)、編碼和測試,幾乎支持所有語言)。

springfox大致原理:

springfox的大致原理就是,在項(xiàng)目啟動(dòng)的過種中,spring上下文在初始化的過程, 框架自動(dòng)跟據(jù)配置加載一些swagger相關(guān)的bean到當(dāng)前的上下文中,并自動(dòng)掃描系統(tǒng)中可能需要生成api文檔那些類, 并生成相應(yīng)的信息緩存起來。如果項(xiàng)目MVC控制層用的是springMvc那么會(huì)自動(dòng)掃描所有Controller類,并生成對(duì)應(yīng)的文檔描述數(shù)據(jù).該數(shù)據(jù)是json格式,通過路徑:項(xiàng)目地址/ v2/api-docs可以訪問到該數(shù)據(jù),然后swaggerUI根據(jù)這份數(shù)據(jù)生成相應(yīng)的文檔描述界面。 因?yàn)槲覀兡苣玫竭@份數(shù)據(jù),所以我們也可以生成自己的頁面.

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以上才能運(yùn)行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"))//這里填寫項(xiàng)目package
                .paths(PathSelectors.any())
                .build();
    }//springfox為我們提供了一個(gè)Docket(摘要的意思)類,我們需要把它做成一個(gè)Bean注入到spring中, 顯然,我們需要一個(gè)配置文件,并通過一種方式(顯然它會(huì)是一個(gè)注解)告訴程序,這是一個(gè)Swagger配置文件。
  
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2構(gòu)建RESTful API")
                .description("rest api 文檔構(gòu)建利器")
                .termsOfServiceUrl("https://www.cnblogs.com/yrxing/")
                .contact("xing")
                .version("1.0")
                .build();
    }
  
}//springfox允許我們將信息組合成一個(gè)ApiInfo的類,作為構(gòu)造參數(shù)傳給Docket

2021413113443574

2021413113506972

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

Swagger2常用注解使用

2021413113551941

@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 ,該字段或者方法就不會(huì)被生成api文檔.
    private String password;
  
    private String email;
  
    private Integer age;
  
    private Boolean enabled;
  
}

@ApiParam()

@ApiOperation(value = "獲取用戶詳細(xì)信息", notes = "根據(jù)url的id來獲取用戶詳細(xì)信息")
 @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這個(gè)注解,需要注意的是,這個(gè)注解方法的參數(shù)前面,不能直接用在方法上面. 

@ApiImplicitParams()、@ApiImplicitparam()

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

以上就是SpringBoot項(xiàng)目中整合Swagger2的步驟詳解的詳細(xì)內(nèi)容,想要了解更多關(guān)于SpringBoot和Swagger2的其他資料請(qǐng)關(guān)注W3Cschool其它相關(guān)文章!也希望大家多多地支持我們!

0 人點(diǎn)贊