swagger3.0使用及https问题处理

swagger 文档在日常开发中，用得比较多，往往我们都是手动配置，swagger30之后，直接就上了一个swagger-starter,用起来更方便了。swagger30发生了很多变化，比如包名、注解、访问路径等都有所变化。具体自己去体会了，我就是不多说了，直接开干。

swagger30项目地址: >

@Api：用在请求的类上，表示对类的说明 tags="说明该类的作用，可以在UI界面上看到的注解" value="该参数没什么意义，在UI界面上也看到，所以不需要配置" @ApiOperation：用在请求的方法上，说明方法的用途、作用 value="说明方法的用途、作用" notes="方法的备注说明" @ApiImplicitParams：用在请求的方法上，表示一组参数说明 @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面 name：参数名 value：参数的汉字说明、解释 required：参数是否必须传 paramType：参数放在哪个地方 · header --> 请求参数的获取：@RequestHeader · query --> 请求参数的获取：@RequestParam · path（用于restful接口）--> 请求参数的获取：@PathVariable · body（不常用） · form（不常用） dataType：参数类型，默认String，其它值dataType="Integer" defaultValue：参数的默认值 @ApiResponses：用在请求的方法上，表示一组响应 @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息 code：数字，例如400 message：信息，例如"请求参数没填好" response：抛出异常的类 @ApiModel：用于响应类上，表示一个返回响应数据的信息 （这种一般用在post创建的时候，使用@RequestBody这样的场景， 请求参数无法使用@ApiImplicitParam注解进行描述的时候） @ApiModelProperty：用在属性上，描述响应类的属性 @Api：用在请求的类上，说明该类的作用

@Api：用在请求的类上，说明该类的作用 tags="说明该类的作用" value="该参数没什么意义，所以不需要配置"

@ApiOperation：用在请求的方法上，说明方法的作用

@ApiOperation："用在请求的方法上，说明方法的作用" value="说明方法的作用" notes="方法的备注说明"

示例：

@ApiOperation(value="用户注册",notes="手机号、密码都是必输项，年龄随边填，但必须是数字")

@ApiImplicitParams：用在请求的方法上，包含一组参数说明

@ApiImplicitParams：用在请求的方法上，包含一组参数说明 @ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息 name：参数名 value：参数的汉字说明、解释 required：参数是否必须传 paramType：参数放在哪个地方 · header --> 请求参数的获取：@RequestHeader · query --> 请求参数的获取：@RequestParam · path（用于restful接口）--> 请求参数的获取：@PathVariable · body（不常用） · form（不常用） dataType：参数类型，默认String，其它值dataType="Integer" defaultValue：参数的默认值

示例

@ApiImplicitParams({ @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"), @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"), @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")})

@ApiResponses：用于请求的方法上，表示一组响应

@ApiResponses：用于请求的方法上，表示一组响应 @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息 code：数字，例如400 message：信息，例如"请求参数没填好" response：抛出异常的类

示例

@ApiOperation(value = "select1请求",notes = "多个参数，多种的查询参数类型")@ApiResponses({ @ApiResponse(code=400,message="请求参数没填好"), @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")})

@ApiModel：用于响应类上，表示一个返回响应数据的信息

@ApiModel：用于响应类上，表示一个返回响应数据的信息 （这种一般用在post创建的时候，使用@RequestBody这样的场景， 请求参数无法使用@ApiImplicitParam注解进行描述的时候） @ApiModelProperty：用在属性上，描述响应类的属性

示例 import ioswaggerannotationsApiModel;import ioswaggerannotationsApiModelProperty; import javaioSerializable; @ApiModel(description= "返回响应数据")public class RestMessage implements Serializable{ @ApiModelProperty(value = "是否成功") private boolean success=true; @ApiModelProperty(value = "返回对象") private Object data; @ApiModelProperty(value = "错误编号") private Integer errCode; @ApiModelProperty(value = "错误信息") private String message; / getter/setter /}

一直使用swagger，最近发现一款在swagger基础开发的api文档接口生成框架swagger-spring-boot-starter。我们先看看他生成的效果吧。

1加入依赖

2添加配置

springswaggerenabled=true

springswaggersecurityfilter-plugin=true

# 配置

springswaggerapi-keykey-name=myToken

# 201 版本新特性 （支持可选的 Bean 验证插件）

# 配置账号密码

springswaggersecurityusername=battcn

springswaggersecuritypassword=battcn

springswaggerbase-package=comcornerstoneverificationcontroller

# 关闭 JSR

springswaggervalidator-plugin=false

3启动项目输入：>

Swagger2一些常用注解

最近遇到了一个使用swagger来生成接口文档的项目，在controller看到了一些没用过的注解（@API、@ApiOperation等），遂记录一下

@API

使用在类上，表明是swagger资源，@API拥有两个属性:value、tags，源码如下

//If tags is not used,this value will be used to set the tag for the operations described by this resource Otherwise, the value will be ignored

String value() default "";

//Tags can be used for logical grouping of operations by resources or any other qualifier

String[] tags() default {""};

1

2

3

4

5

生成的api文档会根据tags分类，直白的说就是这个controller中的所有接口生成的接口文档都会在tags这个list下；tags如果有多个值，会生成多个list，每个list都显示所有接口

@Api(tags = "列表1")

@Api(tags = {"列表1","列表2"})

1

2

value的作用类似tags,但是不能有多个值

@ApiOperation

使用于在方法上，表示一个>

Spring 使用Swagger来生成接口文档时，当请求为GET请求时且入参为一个对象则需要通过在接口请求的入参对象前面加一个注解 @ModelAttribute。

@ModelAttribute 注解在方法参数上面的时候代表这个对象从URL或者表单获取(该注解所属为Spring Framework)。

Swagger 版本号

1Springboot整合Swagger2

11pom加swagger依赖

<dependency>

         <groupId>iospringfox</groupId>

         <artifactId>springfox-swagger2</artifactId>

         <version>292</version>

      </dependency>

      <!-- <dependency>

         iospringfox

         springfox-swagger-ui

         292

      -->

      <dependency>

            <groupId>comgithubxiaoymin</groupId>

            <artifactId>swagger-bootstrap-ui</artifactId>

            <version>190</version>

        </dependency>

      <dependency>

          <groupId>ioswaggercorev3</groupId>

          <artifactId>swagger-annotations</artifactId>

          <version>208</version>

      </dependency>

        <dependency>

          <groupId>ioswaggercorev3</groupId>

          <artifactId>swagger-models</artifactId>

          <version>208</version>

</dependency>

12添加swagger配置类

@Configuration

@EnableSwagger2

@EnableSwaggerBootstrapUI

//@ConditionalOnExpression("${swaggerenable:true}")

public class Swagger2 {

//    @Override 

//    public voidaddResourceHandlers(ResourceHandlerRegistry registry) { 

//       registryaddResourceHandler("swagger-uihtml")addResourceLocations("classpath:/META-INF/resources/"); 

//        registryaddResourceHandler("/webjars")addResourceLocations("classpath:/META-INF/resources/webjars/"); 

//    } 

   @Value("${swaggerenable:true}")

   private String enable;

   @Value("${swaggerbasePackage}")

   private String basePackage;

   @Bean

   public Docket createRestApi()

{

      Predicateselector= PathSelectors none ();

      if ("true"equals(enable)) {

         selector=PathSelectors any ();

      }

      //定义全局参数

       Listpars = new ArrayList<>();

          ParameterBuildertoken = new ParameterBuilder();

          tokenname("token")description("token")modelRef( new ModelRef("string"))parameterType("header")required( false )build();

          parsadd(tokenbuild());

      return new Docket(DocumentationType SWAGGER_2 )

            globalOperationParameters(pars) // 全局参数

            groupName("demo01")//指定分组

            apiInfo(apiInfo())

            select()

            apis(RequestHandlerSelectors basePackage (basePackage))

//          paths(PathSelectorsany())

            paths(selector)

            build();

   }

   private ApiInfo apiInfo() {

      return new ApiInfoBuilder()

            title("SpringBoot测试使用 Swagger2 构建RESTful API")

            description("springboot demo 接口文档")

            version("10")

            build();

   }

}

13加上swagger启用禁用开关

新建applicationproperties文件

#swagger启用禁用标识true：启用

swaggerenable=true

#swagger扫描需生成文档的包路径

swaggerbasePackage=comtjcspringbootDemocontroller

14Swagger具体注释用法

>

swagger 不同目录下的controller怎么设置

会扫描配置的API文档格式自动生成一份json数据，而swagger官方也提供了ui来做通常的展示，当然也支持自定义ui的。不过对后端开发者来说，能用就可以了，官方就可以了。

最强的是，不仅展示API，而且可以调用访问，只要输入参数既可以try it out

以上就是关于swagger3.0使用及https问题处理全部的内容，包括:swagger3.0使用及https问题处理、Swagger2 UI 提示"请确保swagger资源接口正确"解决办法、swagger歌曲（swagger2注解详细说明）等相关内容解答，如果想了解更多相关内容，可以关注我们，你们的支持是我们更新的动力！