Swagger 这么学,你学废了吗?

484 阅读2分钟

这是我参与更文挑战的第7天,活动详情查看: 更文挑战

前言

相信大家平时开发的过程中,都会使用到 API文档工具吧?大家都在使用什么呀?Java docs,I/O Docs, apiary.io, Docco, Dexy, Doxygen, TurnAPI,Swagger。今天我就来教大家如何使用 Swagger 搭建 API 文档。

什么是swagger?

  • 世界上最流行的Api框架;
  • RestFul Api 文档在线自动生成工具;
  • 文档和实现保持同步和自动更新来简化API的构建过程;
  • 直接运行,可以在线测试API接口;
  • 支持多种语言:(java ,php...)

Swagger-core注解

NameDescription
@Api标记为 Swagger 资源
@ApiModel标记为 Swagger 模型
@ApiModelProperty模型字段的属性说明
@ApiOperationhttp接口的说明
@ApiParamhttp 接口参数说明

更多详细的说明可以参考 github上的解释:github.com/swagger-api…

springboot集成swagger

  1. 新建一个springboot项目 =>web项目
  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>
  1. 配置swagger信息
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(Environment environment){

        //根据开发环境的不同,是否开启swagger
        Profiles profiles = Profiles.of("pro");
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
            //    .enable(flag)  //enable是否开启Swagger 默认是true,如果是false,则swagger不能在浏览器中
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cn.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo(){
        Contact contact=new Contact("初念初恋","https://juejin.cn/user/3940246036953293","13145200@qq.com");
        return new ApiInfoBuilder()
                .title("后台管理系统 API文档")
                .description("越努力越幸运")
                .termsOfServiceUrl("https://juejin.cn/user/3940246036953293")
                .version("1.0")
                .contact(contact)
                .build();
    }

}
  1. controller层
@Controller
public class LoginController {

    @GetMapping(value = "/toLogin")
    public String toLogin(){
        return "login";
    }

    @ApiOperation(value = "登录")
    @PostMapping("/login")
    public String login(
            @RequestParam("username") String username,
            @RequestParam("password") String password,
            Model model){
        Subject subject = SecurityUtils.getSubject();
        UsernamePasswordToken token = new UsernamePasswordToken(username,password);
        try {
            subject.login(token);
            return "index";
        }catch (UnknownAccountException uae){
            model.addAttribute("msg","用户不存在");
            return "login";
        }catch (IncorrectCredentialsException ice){
            model.addAttribute("msg","密码不正确");
            return "login";
        }
    }

    @GetMapping("/logOut")
    public String logOut(){
        return "login";
    }

    @GetMapping("/noAuthorization")
    public String noAuthorization(){
        return "未经授权,无法访问此页面";
    }
}
@Controller
@RequestMapping("/userInfo")
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping("/userList")
    public String getUserList(){
        return "userList";
    }

    @GetMapping("/userAdd")
    public String addUser(){
        return "addUser";
    }

    @GetMapping("/userDel")
    public String deleteUser(){
        return "deleteUser";
    }

    @GetMapping("/getList")
    public List<UserInfo> getList(int id){
        return userService.getList(id);
    }

    @ApiOperation(value = "根据用户名查找用户信息")
    @GetMapping("/findByUsername")
    public UserInfo findByUsername(@RequestParam("username") String username){
        return userService.findByUsername(username);
    }
}
  1. 浏览器访问:http://localhost:8080/swagger-ui.html

image-20210629123114873

结尾

  1. Swagger可以充当前后端交流的重要桥梁,方便快捷。很实用。

  2. Swagger项目允许你生产,显示和消费你自己的RESTful服务。不需要代理和第三方服务。是一个依赖自由的资源集合,它能通过Swagger API动态的生成漂亮的文档和沙盒,因为Swagger UI没有依赖,你可以把他部署到任何服务器环境或者是你自己的机器。