Swagger

优势

  • 号称世界上最流程的api框架

  • 支持多种语言(java php)

  • 能够直接运行

  • 自动生成接口文档

官网

http://swagger.io

在项目中使用swagger需要springbox

  • swagger2
  • ui

用springboot集成swagger

导入依赖

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

配置Swaggerconfig配置类(当然不配置也会有默认的)

@Configuration
@EnableSwagger2
public class swaggerConfig  {
   @Bean
    public Docket docket(Environment environment){
        //Reques tHandlerSelectors,配置要扫描接口的方式
        //basePackage :指定要扫描的包
        //any():扫描全部
        //none();不扫描
        //withClassAnnotation:扫描类上的注解,参数是一个注解的反射对象
        //wi thMethodAnnotation:扫描方法上的注解
        //paths()过滤  ant("/**")常用
        //Enable() ---true启动,false 禁用,默认启用
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.hzx.swaggerdemo.cotroller")).paths(PathSelectors.ant("/**")).build();
    }

    public ApiInfo apiInfo(){
        Contact contact =new Contact("hzx","http://116.62.102.168/blog","1620899079@qq.com ");
        return new ApiInfo("接口文档","controller下的接口文档","v1.0","",contact,"apach2.0","",new ArrayList<>());
    }
 }

关于实体对象以及注释

当你的controller方法中有返回实体对象,那么也会记录到swagger中,当然有时候有些实体类的字段会看不懂,所以swagger也提供了一些注释用的注解,用来给字段或者类名注释

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    private String name ;
    @ApiModelProperty("用户密码")
    private String password;
    
}


//在controller层中也可以在方法上面加入ApiOperation()来提供注释
@Controller
public class HelloController {
    @ApiOperation("问好")
    @GetMapping("/hello")
    @ResponseBody
    public String hello(){
        return "hello Swagger";
    }
}

如何让swagger只在开发阶段使用,上线之后禁用

image-20200304165136400

public class swaggerConfig  {
    @Bean
    public Docket docket(Environment environment){
        //Reques tHandlerSelectors,配置要扫描接口的方式
        //basePackage :指定要扫描的包
        //any():扫描全部
        //none();不扫描
        //withClassAnnotation:扫描类上的注解,参数是一个注解的反射对象
        //wi thMethodAnnotation:扫描方法上的注解
        //paths()过滤  ant("/**")常用
        //Enable() ---true启动,false 禁用,默认启用
        Profiles profiles=Profiles.of("dev","test");//如果是这样的环境那么就返回true,否则false
        boolean flag= environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(flag).select().apis(RequestHandlerSelectors.basePackage("com.hzx.swaggerdemo.cotroller")).paths(PathSelectors.ant("/**")).build();
    }

配置API文档分组

.groupName("组名")
@Bean
public Docket docket(Environment environment){
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("组名");
}

swagger支持在线测试

点击“try it out” 按钮 即可

当然重在实践,所以赶快参数去吧

Q.E.D.

知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议

只有不断的努力才会有更大的惊喜等着你去发现!!