Swagger应用

swagger简单配置

Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。

1. 简单的提供接口Swagger配置(SpringBoot)

1. SpringBoot主启动类添加Swagger注解

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

2. yml 基本参数设置

   swagger:
   # 是否开启swagger文档
     enabled: true 
     title: API文档-本地环境
     exclude-path: /error, /ops/**,/actuator,/actuator/**
   

2. 带有web页面的Swagger配置(SpringBoot)

1. 带有web页面的必须自己写Swagger配置类

2. 配置类上必须加上@EnableSwagger2Doc注解

   /**
    * @author fzz
    */
   @Configuration
   @EnableSwagger2Doc
   public class SwaggerConfig implements WebMvcConfigurer {
   
   	//是否开启swagger文档
       private Boolean enabled = true;
   	private String TITLE = "API文档-本地环境";
   	private String VERSION = "1.0";
   
       private static final String BASE_PACKAGE = "com.web.controller";
       private static final String SWAGGER_UI = "swagger-ui.html";
   	private static final String SWAGGER_RESOURCES = "classpath:/META-INF/resources/";
       private static final String SWAGGER_WEB_JAR = "/webjars/**";
       private static final String SWAGGER_RESOURCES_WEB_JAR = "classpath:/META-INF/resources/webjars/";
       /**
        *	和下面yml配置文件二选一
        */
   	@Bean
       public Docket createRestApi() {
           return new Docket(DocumentationType.SWAGGER_2).enable(enabled)
                   .apiInfo(apiInfo())
                   .select()
                   .apis(RequestHandlerSelectors.basePackage(BASE_PACKAGE))
                   .paths(PathSelectors.any())
                   .build();
       }
    
       private ApiInfo apiInfo() {
           return new ApiInfoBuilder().title(TITLE).version(VERSION).build();
       }
   
       @Override
       public void addResourceHandlers(ResourceHandlerRegistry registry) {
           registry.addResourceHandler(SWAGGER_UI).addResourceLocations(SWAGGER_RESOURCES);
           registry.addResourceHandler(SWAGGER_WEB_JAR).addResourceLocations(SWAGGER_RESOURCES_WEB_JAR);
       }
   
   }
   
   

   一些环境变量可以写在yml中

   swagger:
     enabled: true
     title: WEB文档-测试环境
     version: 1.0
     exclude-path: /error, /ops/**, /actuator/**
     base-package: com.open.manager.controller
   

3. 带有web页面的Swagger配置(ssm)

@Configuration
@EnableWebMvc  
@EnableSwagger2
public class Swagger2Configuration extends WebMvcConfigurationSupport{
	
	@Bean  
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.controller"))
                .paths(PathSelectors.any())  
                .build();  
    }

	@SuppressWarnings("deprecation")
	private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("FX_EXPERT_RANKINGS_WEB.API")
                .termsOfServiceUrl("")
                .contact("")
                .version("1.0")
                .build();
    }  
}

4. Swagger controller格式

   @Controller
   @RequestMapping(value="/api", produces={"application/json;charset=UTF-8"})
   @Api(tags="AppController",description="Controller（移动端）")
   public class AppController extends BaseController {
   	
   	@ApiOperation(value="Method",httpMethod = "PUT",notes=
   			"<font color=red>Authorization参数为请求头信息，程序请求时需要携带该信息，通过swagger调用时可在参数列表中添加</font></br>"+
   			"传入参数提示：<font color=blue>………………</font><br/>"+
   			"接口返回提示：<br/>"+ 
   			"1、该接口需根据返回的code和subCode进行逻辑判断，均为0时表示操作成功并返回信息。<br/>" + 
   			"2、code为0，subCode为800004时，<font color=red>………………</font>。<br/>" )
   	@ApiResponses({@ApiResponse(code = 200, message = "ok", response=ReturnModel.class)})
   	@ApiImplicitParams({
   		@ApiImplicitParam(name = "uid", required = true, value = "用户ID", paramType = "query", dataType = "int")})
   	@RequestMapping(value="/putDemo",method=RequestMethod.PUT)
   	public @ResponseBody ReturnModel putDemo(
   			@RequestParam(required=true)Integer uid){
   		return demoService.putDemo(uid));
   	}
   

5. Swagger Model格式

   //属性首字母大写的时候必须加上@JsonProperty，@JsonIgnore注解
   @ApiModel
   public class TDAccountTinyModel {
   
   	@JsonProperty(value = "AccountId")
   	@ApiModelProperty(value = "账户ID")
   	private Integer AccountId;
       
       @JsonIgnore
   	public Integer getAccountId() {
   		return AccountId;
   	}
   
   	public void setAccountId(Integer accountId) {
   		AccountId = accountId;
   	}
   }
   //属性首字母小写
   @ApiModel
   public class TDAccountTinyModel {
   
   	@ApiModelProperty(value = "账户ID")
   	private Integer accountId;
       
   	public Integer getAccountId() {
   		return accountId;
   	}
   
   	public void setAccountId(Integer accountId) {
   		accountId = accountId;
   	}
   }