Swagger入门

Swagger

组件

1. Springfox swagger2：用于扫描接口信息
2. Springfox Swagger UI： 用于生成可视化文档

结合SpringBoot创建配置类

• 配置类：

  @Configuration
  public class SwaggerDemo {
      
      @Bean
      public Docket getDocket(){
          Docket docket = new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(getApiInfo()) // 设置文档封面，文档标题，描述，版本，联系方式等
                  .select() //监控哪些接口，如果不填写，代表所有
                  .apis(RequestHandlerSelectors.basePackage("com.yuanheng.controller")) //指定文档扫描包的范围
                  .paths(PathSelectors.any()) // 指定生成api的路径，即“/xxx”
                  .build();
          return docket;
      }
      
      public ApiInfo getApiInfo() {
          ApiInfo apiInfo = new ApiInfoBuilder()
                  .title("图书管理系统接口文档")
                  .description("此文档描述了...")
                  .version("v1.2")
                  .contact(new Contact("smithisme", "yuanhengwcn@gitee.com", "yuanhengwcn@foxmail.com"))
                  .build();
          return apiInfo;
      }
      
  }
  

访问地址

启动之后，启动localhost:8080/项目路径/swagger-ui.html即可查看接口API

注解

1. @Api，属性tags，在生成文档的包的标题位置标注相关信息。

   • 代码实例

     @Api(tags = "图书信息管理接口")
     public class BookController {
     	...
     }
     

   • 作用范围

     类注解，解释说明当前控制器类的作用。

   • 显示状态

     

2. @ApiOperation，属性value, notes

   • 代码实例：

     @RequestMapper(value = "/add", method = RequestMethod.POST)
     @ApiOperation(value = "添加图书信息", notes = "调用此接口的注意事项")
     public ResultVO saveBook(@RequestBody Book book) {
         ...
     }
     

   • 作用范围

     接口方法注解，解释说明接口的作用

   • 显示状态

     

3. ApiImplicitParam，属性paramType

   • 代码实例

     @ApiImplicitParam(paramType = "path", name = "id", value = "要删除的图书Id", required = true, dataType = "int")
     public ResultVO deleteBook(@PathVariable("id") Integer bookId) {
         ...
     }
     

   • 作用范围

     接口方法注解，解释说明参数的作用

   • 参数解析

     1. paramType：

        • path代表参数来源于路径，通过路径传进来的
        • header代表参数从http请求的header(请求头)传进来的
        • query代表参数通过路径url + ? 传进来的，拼接在url上

     2. required：

        • 是否是必要参数，若为true，在UI中以*结尾

4. ApiImplicitParams

   • 代码实例

     @ApiImplicitParams({
         @ApiImplicitParam(paramType = "query", name = "pageNum", value = "页码", required = true, dataType = "int"),
         @ApiImplicitParam(paramType = "query", name = "pageSize", value = "每页条数", required = true, dataType = "int")
     })
     public ResultVO listBook(Integer pageNum, Integer pageSize) {
         ...
     }
     

5. ApiModel，属性value，description

   • 代码实例

     @Data
     @NoArgsConstructor
     @AllArgsConstructor
     @ApiModel(value = "Book对象", description = "图书信息")
     public class Book {
         ...
     }
     

6. ApiModelProperty，属性value, dataType, required

   • 代码实例

     @Data
     @NoArgsConstructor
     @AllArgsConstructor
     @ApiModel(value = "Book对象", description = "图书信息")
     public class Book {
         @ApiModelProperty(value = "图书Id", dataType = "int", required = true)
         private Integer id;
     }