Swagger配置及美化

  • A+
所属分类:swagger

前后端分离

最常见的:Vue + SpringBoot

前后端分离,后台负责写接口。随着接口越来越多,随时改变接口的可能性也很大,大家争吵是很正常的。

解决方案

  • 先指定计划提纲,事实更新API,降低集成风险

  • 传统是需要自己去维护一个doc的文档或者公司统一放在一个接口清单的web服务上。每次开发者需要单独添加上去。修改后还需要维护。

  • 前后端分离:

    • 前端测试后端接口:postman,就为了测一个接口还要下载第三方软件,太奢侈了

    • 后端提供接口,实时更新消息及变动

现接入swagger,通过简单的注解即可生成文档,并且随着接口变化自动会变化。统一管理方便快捷

Swagger

  • 号称最流行的API框架

  • RestFul Api 文档在线自动生产,Api文档与定义同步更新

  • 直接运行,可以在线测试接口

  • 支持多种语言(java、php等)

官网:https://swagger.io/

SpringBoot集成Swagger

1.新建SpringBoot项目
2.导入依赖

    <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>

3.随便写一个controller接口,比如 hello
4.配置swagger2,swagger2 是新版的,和swagger 是不一样的哦!

/**
 * @author : aBiu---
 *
 * create at:  2019-12-20  16:20
 *
 * description: api接口配置
 */@Configuration@EnableSwagger2     // 开启public class SwaggerConfig {
  private ApiInfo apiInfo() {
    return new ApiInfoBuilder().title("API接口文档") //页面标题
        .description("接口管理")//详细描述
        .version("1.0.0") //版本号
        .build();
  }
  @Bean
  public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())     // 需要上面定义的ApiInfo,信息显示到页面上
        .groupName("aBiu")      // 分组,如果想搞多个分组,就写多个Docket 的示例就行了
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.*")) //这里写的是API接口所在的包位置,也可以设置其他扫描方式
        .paths(PathSelectors.any())     // 过滤,有好几种方式可以设置
        .build();
  }}

5.测试运行,然后访问:http://localhost:8080/swagger-ui.html 或 http://localhost:8080/swagger-ui/index.html

Swagger配置及美化

由于版本的不同,可能名字不一样,具体可以到jar包里去看一下就好了

Swagger配置及美化

Swagger注解

@Api:          修饰类,一般来描述Controller的@ApiOperation:     描述类的 方法 或者 接口@ApiParam:       单个参数描述@ApiModel:       用在实体类上面@ApiProperty:     实体类里面的属性@ApiImplicitParam:      用在 @ApiImplicitParams 注解中,指定一个请求参数的配置信息               
                name:参数名        
                value:参数的汉字说明、解释        
                required:参数是否必须传        
                paramType:参数放在哪个地方            · 
                header --> 请求参数的获取:@RequestHeader            · 
                query --> 请求参数的获取:@RequestParam            · 
                path(用于restful接口)--> 请求参数的获取:@PathVariable            · 
                body(不常用)            · 
                form(不常用)            
                dataType:参数类型,默认String,其它值dataType="Integer"                               defaultValue:参数的默认值
                其它若干@ApiResponse:     描述HTTP响应其中1个的描述@ApiResponses:     描述出HTTP响应整体描述@ApiClass@ApiError@ApiErrors@ApiParamImplicit@ApiParamsImplicit

示例:一个接口的说明(controller类)

/**
     * XXX 认证人员信息接口
     * @param signerType
     * @param certType
     * @param certNo
     * @param name
     * @param phoneNo
     * @param cardNo
     * @param signSupplier
     * @param authType
     * @param notifyUrl
     * @return
     */
    @ApiOperation(value = "XXX 的接口", httpMethod = "POST")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "String", name = "signerType", dataType = "String", required = true, value = "签署人类型:1.个人,2.企业"),
            @ApiImplicitParam(paramType = "String", name = "certType", dataType = "String", required = false, value = "证件类型:签署人类型是个人时必填"),
            @ApiImplicitParam(paramType = "String", name = "certNo", dataType = "String", required = false, value = "签署人类型:签署人类型是个人时必填"),
            @ApiImplicitParam(paramType = "String", name = "name", dataType = "String", required = true, value = "姓名"),
            @ApiImplicitParam(paramType = "String", name = "phoneNo", dataType = "String", required = false, value = "手机号:签署人类型是个人时必填"),
            @ApiImplicitParam(paramType = "String", name = "notifyUrl", dataType = "String", required = false, value = "回调地址")
    })
    @PostMapping("/signerInfo")
    public ResultInfo signerInfo(String signerType, String certType, String certNo, String name, String phoneNo, @RequestParam(required = false) String notifyUrl){
        return contractService.signerInfo(signerType,certType,certNo,name,phoneNo,cardNo,signSupplier,authType,notifyUrl);
    }
项目发布上线时候,一定要记得,一定要记得,把swagger 关闭,因为你不可能让用户看到你的接口吧?

生成漂亮的ui界面

加入依赖

    <dependency>
        <groupId>com.github.caspar-chen</groupId>
        <artifactId>swagger-ui-layer</artifactId>
        <version>1.1.3</version>
    </dependency>

访问地址 http://localhost:8080/docs.html

这个好像没有分组的属性,如果swagger配置时候加了分组,在这里会有异常

Swagger配置及美化

发表评论

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen: