码迷,mamicode.com
首页 > 其他好文 > 详细

swagger使用

时间:2018-07-27 13:16:47      阅读:150      评论:0      收藏:0      [点我收藏+]

标签:rms   登陆   linked   分公司   展开   分系统   enables   log   sof   

 

一 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.lianjia.credit.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("信用分系统——api文档")
                .description("让我们一起把信用分做好做强大")
                .termsOfServiceUrl("http://wiki.lianjia.com/pages/viewpage.action?pageId=169935067")
                .version("1.0")
                .build();
    }
}

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

@Api(description = "分公司相关接口", tags = {"company"})
@RestController
public class CreditScoreCompController 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/comp/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,中文的时候不能展开接口列表,需要用英文
?  注意:线上环境建议关闭
?  代码侵入性
?  如果系统控制内网访问,无法提供接口文档给其他公司人看

swagger使用

标签:rms   登陆   linked   分公司   展开   分系统   enables   log   sof   

原文地址:https://www.cnblogs.com/wanghongsen/p/9376852.html

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!