Swagger-UI 之 简单使用

Swagger-UI的简单使用

1.什么是Swagger-UI
Swagger
Swagger UI允许任何人（无论您是开发团队还是最终用户）都可以可视化API资源并与之交互，而无需任何实现逻辑。它是根据您的OpenAPI（以前称为Swagger）规范自动生成的，具有可视化文档，可简化后端实现和客户端使用。

下面让我们看看在项目中如何使用
这里用到的是spring Boot
导入maven 依赖

 
        org.springframework.boot
        spring-boot-starter-parent
        2.1.3.RELEASE
        
    

    
        Greenwich.RELEASE
    

    
        
            org.springframework.cloud
            spring-cloud-dependencies
            ${spring-cloud.version}
            pom
            import
        
        
            io.springfox
            springfox-swagger2
            2.8.0
        
        
            org.springframework.boot
            spring-boot-starter-web
        
        
            io.springfox
            springfox-swagger-ui
            2.8.0
        
    
    
        
            
                org.springframework.boot
                spring-boot-maven-plugin
                2.1.3.RELEASE
            
        
    

为程序分配端口号：

server:
  port: 38682

建立启动器

package com.cs.swagger;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SwaggerApplication {
     
    public static void main(String[] args) {
     
        SpringApplication.run(SwaggerApplication.class,args);
    }
}

建立接口文档生成类

package com.cs.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
     

    @Bean
    public Docket api(){
     
        return new Docket(DocumentationType.SWAGGER_12)
        		// 当前的ip 和 端口号  为那个服务产生 接口文档
                .host("127.0.0.1:38682") 
                .apiInfo(apiInfo())
                .select()
                //指定对应的接口类
                .apis(RequestHandlerSelectors.basePackage("com.cs.swagger.controller"))  
                .paths(PathSelectors.any())
                .build();
    }

	//接口文档的信息
    private ApiInfo apiInfo(){
     
        return new ApiInfoBuilder()
                //标题
                .title("我的API文档")
                //描述
                .description("我的测试接口文档")
                //版本号
                .version("1.0")
                .build();
    }
}

对应的controller

package com.cs.swagger.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;


@RestController
@Api(value = "@Api 修饰整个类，描述Controller的作用")
public class SwaggerController {
     
    @GetMapping("/hello/{name}")
    @ApiOperation(value = "描述一个类的方法，或者说是一个接口")
    public String hello(
            @ApiParam(value = "单个参数的描述",example = "举一个例子")@PathVariable(value = "name") String name){
     
        return "hello" + name;
    }

}

配置完毕直接运行启动类就可以了
然后我们访问 http://localhost:38682/swagger-ui.html 即可访问接口文档
里面带着我们之前设置的详细信息

 @Api：修饰整个类，描述Controller的作用
 @ApiOperation：描述一个类的一个方法，或者说一个接口
 @ApiParam：单个参数描述
 @ApiModel：用对象来接收参数
 @ApiProperty：用对象接收参数时，描述对象的一个字段
 @ApiResponse：HTTP响应其中1个描述
 @ApiResponses：HTTP响应整体描述
 @ApiIgnore：使用该注解忽略这个API
 @ApiError ：发生错误返回的信息
 @ApiImplicitParam：一个请求参数
 @ApiImplicitParams：多个请求参数