Swagger2使用小记

环境：

SpringBoot 2.0.4.RELEASE + Mybatis3.4.6 + Maven3.5.3 + Swagger2.9.2 + Lombok1.18.2

工具：

IDEA

这个项目做了有一段时间了，但是还没有什么大的进展，关于swagger2，使用起来也比较简单，网上有许多教程，我是看书《深入理解Spring Could与微服务构建》这本书，里面简单的介绍了swagger2的使用，然后个人又搜集了一些知识点，进行了补充。

贴代码：

1，swagger配置类。

@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {

    @Bean
    public Docket createRestfulApi() {

        ParameterBuilder parameterBuilder = new ParameterBuilder();

        parameterBuilder
                .parameterType("header") //参数类型支持header, cookie, body, query etc
                .name("token") //参数名
                .defaultValue("asdf") //默认值
                .description("可以不用提供token")
                .modelRef(new ModelRef("String"))//指定参数值的类型
                .required(false)
                .build(); //非必需，这里是全局配置，然而在登陆的时候是不用验证的
        List<Parameter> parameterList = new ArrayList<>();
        parameterList.add(parameterBuilder.build());

        parameterBuilder.parameterType("header")
                .name("api-key")
                .defaultValue("123")
                .description("一定要提供api-key")
                .modelRef(new ModelRef("String"))
                .required(true)
                .build();
        parameterList.add(parameterBuilder.build());

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).globalOperationParameters(parameterList)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ifeng.zlphb.controller"))
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("use swagger generate restful api document")
                .description("set it up by naison")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }
}

2，controller注解

@RestController
@CrossOrigin
@RequestMapping("/")
@Api(value = "关于用户操作的controller",tags = {"包括了很多个接口","其中的token和api-key请谨慎使用"})
public class UserController {
    @Autowired
    private UserService userService;

    @GetMapping("/find/by/{id}")
    @ApiOperation(value = "获取用户", notes = "使用ID获取用户")
    @ApiImplicitParams(@ApiImplicitParam(name = "id", paramType = "path", dataType = "String", required = true))
    public ResponseEntity<?> findById(@PathVariable String id) {
        return ResponseEntity.status(HttpStatus.OK).body(userService.findUserById(id));
    }

    @PostMapping("/register")
    @ApiOperation(value = "注册用户", notes = "需要提供用户名和密码")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", paramType = "query", dataType = "String", required = true),
            @ApiImplicitParam(name = "password", paramType = "query", dataType = "String", required = true)})
    public ResponseEntity<?> findById(@ModelAttribute User user) {
        return ResponseEntity.status(HttpStatus.OK).body(userService.register(user));
    }

然后打开http://localhost:8080/swagger-ui.html，就可以看见神奇的东东了。