IDEA下swagger的使用

导语

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

介绍

发现了痛点就要去找解决方案。解决方案用的人多了，就成了标准的规范，这就是Swagger的由来。通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。

但即便如此，对于许多开发来说，编写这个yml或json格式的描述文件，本身也是有一定负担的工作，特别是在后面持续迭代开发的时候，往往会忽略更新这个描述文件，直接更改代码。久而久之，这个描述文件也和实际项目渐行渐远，基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring，迅速将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式，在后面需求持续迭代的项目中，显得尤为重要和高效。

使用

视频教程1偏重原理
 视频教程2偏重实例

注意点

导入pom依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

配置swagger的conifg
在config包下新建一个SwaggerConfig类

@Configuration/*配置到springboot配置里*/
@EnableSwagger2/*开启swagger2*/
public class SwaggerConfig {
}

测试

在这里插入图片描述

配置自己的swagger信息

public class SwaggerConfig {

    //配置了swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    //配置Swagger信息
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("zhangshu","https://blog.csdn.net/u010017876","[email protected]");
        return new ApiInfo("第一次使用SwaggerAPI文档"
                , "zhangshu"
                , "1.0"
                , "urn:tos"
                , contact
                , "Apache 2.0"
                , "http://www.apache.org/licenses/LICENSE-2.0"
                , new ArrayList());
    }
}

配置要扫描的接口

    //配置了swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())/*配置Swagger信息*/
                .enable(false)/*是否启用swagger*/
                .select()/*选择哪些路径和api会生成document*/
                .apis(RequestHandlerSelectors/*RequestHandlerSelectors配置要扫描接口的方式*/
                        /*basePackage指定要扫描的包()最常用*/
                        .basePackage("com.zhangshu.swagger.controller"))
                .build();
    }

根据不同环境使用不同配置,在开发环境下使用swagger,在生产环境下不使用

 //配置了swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){

        /*设置要显示的swagger环境
        * 检测到application.properties中是spring.profiles.active=dev或者test
        * */
        Profiles profiles = Profiles.of("dev","test");
        //通过判断是否处在自己设定的环境当中,是处在"dev","test"就返回true
        boolean flag = environment.acceptsProfiles(profiles);


        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())/*配置Swagger信息*/
                .enable(flag)/*是否启用swagger*/
                .select()/*选择哪些路径和api会生成document*/
                .apis(RequestHandlerSelectors/*RequestHandlerSelectors配置要扫描接口的方式*/
                        /*basePackage指定要扫描的包()最常用*/
                        .basePackage("com.zhangshu.swagger.controller"))
                .build();
    }

配置API的分组(如何配置多个分组,多个Docket实例即可)

 //配置多个分组
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("a");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("b");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("c");
    }

实体类配置
新建一个pojo包下的User类

@ApiModel("用户类")
public class User {
    @ApiModelProperty("姓名")
    private String userName;
    @ApiModelProperty("密码")
    private String password;

controller类中

@RestController
public class HelloController {

    @PostMapping("/hello")
    public String hello(){
        return "hello";
    }
    @ApiOperation("hello控制方法")
    @GetMapping("/hello2")
    public User hello2(@ApiParam("用户名") String userName){
        return new User();
    }

    @GetMapping("/hello3")
    public String hello3(@ApiParam("用户名") String userName){
        return userName;
    }
}

swagger的测试功能(根据最后一个视频进行测试)

    @GetMapping("/hello3")
    public User hello3(@ApiParam("用户类") User user){
        return user;
    }

controller类上使用api

@Api(tags = "hello控制类")
public class HelloController {}

swagger2中models显示实体类要求是

controller类中的方法,返回的是实体类

    public User hello2(@ApiParam("用户名") String userName){
    	User user = new User("张三","123")
        return user;
    }

加@ResponseBody的参数

其他详细操作点这里

fet518

发布了49 篇原创文章 · 获赞 12 · 访问量 2859

私信关注