swagger2 api管理工具

swagger2的引入
  swagger2是一个api文档管理工具，跟随项目的启动一起启动，嵌入到项目中去的（这一点我不是太喜欢，不过确实是挺方便的，公司最近要引入，所以做一些记录）

项目使用springboot，通过maven进行管理，所以首先引入相关的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>

这里我使用的是2.9.2版本，引入之后再进行相关的配置

swagger的配置：

package com.yishijie;
//我把import的包去掉了，因为有点多
@Configuration
//启动swagger2，这个不引入将无法访问swagger2文档
@EnableSwagger2
//激活的profile仅仅为test,也就是生产不激活swagger2（公司内的项目是多环境的配置）
@Profile({"test"})
public class Swagger2Config {
    @Bean
    public Docket apiBean() {
        //设置一些header相关的信息
        Parameter jwtParam = new ParameterBuilder().name(HttpHeaders.AUTHORIZATION)
                .description("jwt token") //相关描述
                .defaultValue("Bearer xxx") //默认的值
                .modelRef(new ModelRef("string")) // 类型
                .parameterType("header") //类型为header
                .required(true) //是否为必须属性
                .build();

        Parameter userPkParam = new ParameterBuilder().name("Y-YISHIJIE-USER-PK")
                .description("userPk")
                .defaultValue("xxx")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(true)
                .build();


        return new Docket(DocumentationType.SWAGGER_2)
                //设置全局信息
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yishijie"))
                .build()
                //全局参数
                .globalOperationParameters(Arrays.asList(jwtParam, userPkParam));
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //文档的标题
                .title("异世界的api文档")
                //文档的描述
                .description("最美的不是下雨天，而是与你多过雨的屋檐")
                //文档的版本
                .version("1.0")
                .build();
    }
}

swagger的使用：

创建一个controller,然后加入swagger2的相关注解

package com.yishijie;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.util.HashMap;
import java.util.Map;

@RestController
@RequestMapping(value = "/v1")
//整体接口的说明
@Api(tags = {"hello接口"})
public class HelloController {

    private Map<String,String> contentMap = new HashMap<>();
    @RequestMapping(value = "/hello",method = RequestMethod.POST)
    //value部分接口的说明，notes接口描述response返回结果
    @ApiOperation(value = "hello创建", notes = "hello参数详情")
    //name参数输入名称,要一致；value输入参数实体的描述
    @ApiImplicitParams({
            @ApiImplicitParam(name = "hello", value = "hello输入内容", required = true, paramType = "body", dataType = "Hello")
    })
    public ResponseEntity<?> sayHello(@RequestBody Hello hello){
        contentMap.put(hello.getName(),hello.getText());
        return new ResponseEntity<>(null, HttpStatus.OK);
    }

    @RequestMapping(value = "/hello",method = RequestMethod.GET)
    //value部分接口的说明，notes接口描述response返回结果
    @ApiOperation(value = "hello获取", notes = "hello参数详情", response = HelloResponse.class)
    //name参数输入名称,要一致；value输入参数实体的描述，required是否必须，paramType参数类型（body引用对象body类型，query请求参数类型,path路径参数，比如/status/{userPk}之类的）
    //如果是int类型example必须填，不然请求swagger2的时候会抛异常，defaultValue默认值
    @ApiImplicitParams({
            //如果又多个参数可以写多个，逗号隔开，如果只有一个参数，也可以去掉外部的@ApiImplicitParams注解
            @ApiImplicitParam(defaultValue = "xxx",name = "name", value = "sayHello的用户名", required = true, paramType = "query", dataType = "String")
    })
    public ResponseEntity<?> getHello(@RequestParam String name){
        HelloResponse helloResponse = new HelloResponse();
        helloResponse.setName(name);
        helloResponse.setText(contentMap.get(name));
        return new ResponseEntity<>(helloResponse, HttpStatus.OK);
    }

}

对于body参数类型的，还可对字段进行描述：

package com.yishijie;

import io.swagger.annotations.ApiModelProperty;

public class HelloResponse {

    //body参数类型的字段描述
    @ApiModelProperty(value = "sayHello的用户")
    private String name;
    @ApiModelProperty(value = "sayHello的内容")
    private String text;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getText() {
        return text;
    }

    public void setText(String text) {
        this.text = text;
    }
}

启动项目，然后访问：http://127.0.0.1:8080/swagger-ui.html可以看到：

点开hello创建的接口如下：

这里还有一个好处就是可以在这里调接口，点开右上脚的try it out可以输入参数调用接口访问服务器：

如下图：

然后点击下面的execute即可看到返回结果了，以前我是用postman（每个字段名要自己输入，当右几十个字段的时候，真的麻烦），现在直接这里就可以调试接口了。

一些courses可以看下这个：https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api