zoukankan      html  css  js  c++  java
  • swagger使用

     

    一 swagger简介

    Swagger 是一个用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。可以跟据业务代码自动生成相关的api接口文档

    具有以下好处

    • 及时性 (接口变更后,能够及时准确地通知相关开发人员)
    • 规范性 (能够规范表达接口的地址,请求方式,参数及响应格式和错误信息)
    • 一致性 (接口信息一致,不会出现因开发人员拿到的文档版本不一致,而出现分歧)
    • 可测性 (接口能够测试,以方便理解业务)

    二 使用方法

    1 引入相应jar包(信用分系统使用springboot 1.5.5.RELEAS版本与swagger2.6.1版本适合)

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

    2创建 swagger 配置类(在 springboot 启动类 Application.java 同级创建 Swagger2 的配置类 Swagger2 )

    @Configuration
    @EnableSwagger2
    public class Swagger2 {
    
        @Value("${swagger.enable}")
        private boolean enableSwagger;
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .enable(enableSwagger)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.xx.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("信用分系统——api文档")
                    .description("让我们一起把信用分做好做强大")
                    .termsOfServiceUrl("http://wiki.lianjia.com/pages/viewpage.action?pageId=xxxx")
                    .version("1.0")
                    .build();
        }
    }

    3 在 controller 和 vo 上使用特定含义注解

    @Api(description = "XX相关接口", tags = {"company"})
    @RestController
    public class XXController extends BaseController {
        @Resource
        private QueryCreditScoreCompService queryCreditScoreCompService;
    
        @ApiOperation(value = "查询分公司列表", notes = "查询分公司列表")
        @ApiImplicitParams({
                @ApiImplicitParam(paramType = "query", name = "loginUserCode", dataType = "string", required = true, value = "登陆人系统号")
        })
        @ApiResponses({
                @ApiResponse(code = 999, message = "后端代码异常"),
                @ApiResponse(code = 404, message = "请求url路径错误,或者后端服务未部署启动"),
                @ApiResponse(code = 0, message = "正常返回")
        })
        @RequestMapping(value = "/api/xx/query", method = RequestMethod.GET)
        public JsonResult<List<CompDto>> queryCreditScoreCompList(String loginUserCode) {
            return new JsonResult<>();
        }
    }

    vo模型上添加返回字段含义

    @ApiModel("分公司信息")
    @Data
    public class CompDto {
        @ApiModelProperty("城市编码")
        private String cityCode;
        @ApiModelProperty("城市名称")
        private String compCode;
        @ApiModelProperty("分公司编码")
        private String cityName;
        @ApiModelProperty("分公司名称")
        private String compName;
    }

    访问部署机器的ip+端口+swagger-ui.html,就能看到接口api页面

    三 各个注解用法说明:

    注解描述解释
    @Api Marks a class as a Swagger resource. 用于类对象,只有在类对象上标注该注解后,相应的api信息才能展示出来.
    @ApiOperation Describes an operation or typically a HTTP method against a specific path. 描述具体的方法
    @ApiImplicitParam Represents a single parameter in an API Operation. 描述具体的请求参数,比如具体的响应方法的参数为 HttpServletRequest时,我会从该参数中取一些请求参数,则可以通过该方法单独定义参数.见下面的具体说明,该参数不能单独使用,必须和@ApiImplicitParams一起使用,可参考后面的例子
    @ApiImplicitParams A wrapper to allow a list of multiple ApiImplicitParam objects. 组合一组@ApiImplicitParam
    @ApiParam Adds additional meta-data for operation parameters. 定义具体的请求参数,类似@RequestParam 参数,直接在方法参数上使用.
    @ApiResponse Describes a possible response of an operation. 返回值,该类主要有code值与message两个属性,code值必须是http 返回code值,默认会有200,404等,不能单独使用,必须和@ApiResponses一起使用
    @ApiResponses A wrapper to allow a list of multiple ApiResponse objects. 组合@ApiResponse
    @ApiModel Provides additional information about Swagger models. 提供对请求参数与返回结果中的model的定义

    四 注意的点 / 不足之处:

    •  注意使用版本 springboot1.5.5 对应swagger2.6.1
    •  tags标题由中文bug,中文的时候不能展开接口列表,需要用英文
    •  注意:线上环境建议关闭
    •  代码侵入性
    •  如果系统控制内网访问,无法提供接口文档给其他公司人看
  • 相关阅读:
    SPOJ SAMER08A
    SPOJ TRAFFICN
    CS Academy Set Subtraction
    CS Academy Bad Triplet
    CF Round 432 C. Five Dimensional Points
    CF Round 432 B. Arpa and an exam about geometry
    SPOJ INVCNT
    CS Academy Palindromic Tree
    身体训练
    简单瞎搞题
  • 原文地址:https://www.cnblogs.com/wanghongsen/p/9376852.html
Copyright © 2011-2022 走看看