• springboot使用swagger2生成开发文档


    一、引入jar包

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

      

    二、创建swagger2的配置类

    @Configuration
    @EnableSwagger2
    public class Swagger2 {
        @Bean
        public Docket createRestApi(){
      //多个暴露路径时
      //com.google.common.base.Predicate<RequestHandler> selector1 = RequestHandlerSelectors.basePackage("com.dingzi.project.Controller");
        //com.google.common.base.Predicate<RequestHandler> selector2 = RequestHandlerSelectors.basePackage("com.dingzi.project.apiController");
            return new Docket(DocumentationType.SWAGGER_2)
                    //API基本信息
                    .apiInfo(apiInfo())
                    .select()
                    //暴露路径为当前包路径
                    .apis(RequestHandlerSelectors.basePackage("com.example.learn.swagger2"))
             //多个暴露路径
             //.apis(Predicates.or(selector1,selector2))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    //页面标题
                    .title("Spring Boot 测试使用 Swagger2")
                    //创建人、路径、邮箱
                    .contact(new Contact("dingzi", "", ""))
                    //版本号
                    .version("1.0")
                    //描述
                    .description("API 描述")
                    .build();
        }
    }        
    

      

    三、使用swagger2注解

    @RestController
    @RequestMapping("/api")
    @Api("swagger2Controller测试api")
    @Slf4j
    public class SwaggerDemoController {
    
        @Autowired
        private UserService userService;
    
        @ApiOperation(value = "根据id查询用户", notes = "查询用户信息")
        @ApiImplicitParam(name = "id",value = "用户id",required = true)
        @RequestMapping(value = "/getuser/{id}",method = RequestMethod.GET)
        public User getUser(@PathVariable String id){
            return userService.getUser(id);
        }
    }
    
    •   在controller上的注解

            @Api:用在controller上,表示对类的说明。一般为 

    @Api("swagger2Controller测试api")
     
    
    常用参数:
          tags="说明该类的作用,非空时将覆盖value的值"
           value="描述类的作用"
       其他参数:
          description           对api资源的描述,在1.5版本后不再支持
          basePath              基本路径可以不配置,在1.5版本后不再支持
          position              如果配置多个Api 想改变显示的顺序位置,在1.5版本后不再支持
          produces              设置MIME类型列表(output),例:"application/json, application/xml",默认为空
          consumes              设置MIME类型列表(input),例:"application/json, application/xml",默认为空
          protocols             设置特定协议,例:http, https, ws, wss。
          authorizations        获取授权列表(安全声明),如果未设置,则返回一个空的授权值。
          hidden                默认为false, 配置为true 将在文档中隐藏
    

      

    • 用于方法上(说明参数的含义)

    @ApiOperation:方法的说明      一般为 

    @ApiOperation(value = "根据id查询用户", notes = "查询用户信息")
    常用参数:
          value="说明方法的用途、作用"
           notes="方法的备注说明"
       其他参数:
          tags                操作标签,非空时将覆盖value的值
          response            响应类型(即返回对象)
          responseContainer   声明包装的响应容器(返回对象类型)。有效值为 "List", "Set" or "Map"。
          responseReference  指定对响应类型的引用。将覆盖任何指定的response()类
          httpMethod        指定HTTP方法,"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
          position            如果配置多个Api 想改变显示的顺序位置,在1.5版本后不再支持
          nickname         第三方工具唯一标识,默认为空
          produces            设置MIME类型列表(output),例:"application/json, application/xml",默认为空
          consumes            设置MIME类型列表(input),例:"application/json, application/xml",默认为空
          protocols           设置特定协议,例:http, https, ws, wss。
          authorizations      获取授权列表(安全声明),如果未设置,则返回一个空的授权值。
          hidden              默认为false, 配置为true 将在文档中隐藏
          responseHeaders       响应头列表
          code            响应的HTTP状态代码。默认 200
          extensions       扩展属性列表数组
    

    2、@ApiImplicitParams、@ApiImplicitParam:方法的参数的说明;@ApiImplicitParam 用于指定单个参数的说明,@ApiImplicitParams包含多个@ApiImplicitParam  一般为                                                                         

    @ApiImplicitParam(name = "id",value = "用户id",required = true)
    @ApiImplicitParams({
      @ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"), 
    @ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
      name:参数名,参数名称可以覆盖方法参数名称,路径参数必须与方法参数一致
      value:参数的汉字说明、解释
      required:参数是否必须传,默认为false [路径参数必填]
      paramType:参数放在哪个地方
        ·header --> 请求参数的获取:
      @RequestHeader
        ·query --> 请求参数的获取:
      @RequestParam
        ·path(用于restful接口)--> 请求参数的获取:
      @PathVariable
        ·body(不常用)
        ·form(不常用)
      dataType:参数类型,默认String,其它值dataType="Integer"
      defaultValue:参数的默认值

    3、@ApiResponses、@ApiResponse:方法返回值的状态码说明 一般为

    @ApiResponse(code = 200, message = "请求成功");
    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 400, message = "请求参数没填好"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    })
    @ApiResponses:方法返回对象的说明
    @ApiResponse:每个参数的说明
    	code:数字,例如400
    	message:信息,例如"请求参数没填好"
    	response:抛出异常的类
    
    
    
    • 用于对象上(当请求数据描述,即 @RequestBody 时, 用于封装请求(包括数据的各种校验)数据;当响应值是对象时,即 @ResponseBody 时,用于返回值对象的描述。)

           1、@ApiModel:用于JavaBean上面,表示对JavaBean 的功能描述   一般为

    @ApiModel(value="用户登录信息", description="用于判断用户是否存在")
    参数:    value–表示对象名  
    description–描述

    2、@ApiModelProperty:用在JavaBean类的属性上面,说明属性的含义  一般为 

    @ApiModelProperty(value="用户名")
    
    参数:  value–字段说明 
           name–重写属性名字 
           dataType–重写属性类型 
           required–是否必填 
           example–举例说明 
           hidden–隐藏
    • 用于方法参数上

        1、@ApiParam() 用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等) 一般为

    @ApiParam(name="id",value="用户id",required=true)
    
    参数为:name–参数名 
           value–参数说明 
           required–是否必填    


  • 相关阅读:
    钓鱼网站相关数据
    位置编码
    Nacos 详解,有点东西
    从源码里的一个注释,我追溯到了12年前,有点意思。
    初看一脸问号,看懂直接跪下!
    【git】解决 git clone 时速度较慢
    《码处高效:Java开发手册》之代码风格
    Nginx的安装与运行
    解决windows下WslRegisterDistribution failed with error: 0x80070050的问题
    保姆级教程:VsCode调试docker中的NodeJS程序
  • 原文地址:https://www.cnblogs.com/dinghaoran/p/12929573.html
Copyright © 2020-2023  润新知