配置swagger最简单的做法及如何使用

桃扇骨 2023-10-21 07:22 108阅读 0赞

#### 1.了解swagger ####

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化Resuful风格的Web服务。重要是开源好用。

#### 2.如何搭建（复制即可用） ####

（1）在pom文件中加入swagger依赖

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.5.0</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.5.0</version>
    </dependency>

（2）创建swagger.java

创建一个class，名字随便起。我的名字是Swagger2

@Configuration
    @ComponentScan
    @EnableSwagger2
    public class Swagger2 {
        @Autowired
        private Environment env;
        @Bean
        public Docket petApi() {
            //自定义异常信息
            ArrayList<ResponseMessage> responseMessages = new ArrayList<ResponseMessage>() {
      {
            }};
            return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                    .apis(RequestHandlerSelectors.basePackage("com.sheng.users.controller"))
                    .paths(PathSelectors.any()).build();
        }
        //构建api文档信息
        private ApiInfo apiInfo() {
            return new ApiInfo("education   manage",//大标题
                    "内部接口",//小标题
                    env.getProperty("doc.api.version"),
                    env.getProperty("doc.api.termsOfServiceUrl"),
                    env.getProperty("doc.api.contact"),
                    env.getProperty("doc.api.license"),
                    env.getProperty("doc.api.licenseUrl")
            );
        }
    }

--------------------

其中需要注意这个要改成自己的文件路径：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NzU4NDk3_size_16_color_FFFFFF_t_70][]

（3）最后在启动类中加入注解即可

@EnableSwagger2     //开启swagger

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NzU4NDk3_size_16_color_FFFFFF_t_70 1][]

运行效果如图：

![20181108103525871.png][]

这样swagger就配置完成了。

--------------------

#### 3.swagger的常用注解使用 ####

接下来说一下swagger的几个常用注解：

@Api 用在类上，说明该类的作用。

![2018110810383013.png][]

效果如下：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NzU4NDk3_size_16_color_FFFFFF_t_70 2][]

@ApiOperation 注解来给API增加方法说明

![20181108104037905.png][]

效果如下：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NzU4NDk3_size_16_color_FFFFFF_t_70 3][]

最后再讲一下参数注解

@ApiImplicitParam：用来注解来给方法入参增加说明。

参数详解：

1.name ：参数名。  
2. value ： 参数的具体意义，作用。  
3. required ： 参数是否必填。  
4. dataType ：参数的数据类型。  
5. paramType ：查询参数类型，这里有几种形式：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NzU4NDk3_size_16_color_FFFFFF_t_70 4][]

![20181108104211408.png][]

效果如下：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NzU4NDk3_size_16_color_FFFFFF_t_70 5][]

\-----------------------------------------------

到这里，swagger的配置，以及常用的使用方法就介绍完了，欢迎大家留言。

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NzU4NDk3_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20181108103325746.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NzU4NDk3,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NzU4NDk3_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20181108103427401.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NzU4NDk3,size_16,color_FFFFFF,t_70
[20181108103525871.png]: https://img-blog.csdnimg.cn/20181108103525871.png
[2018110810383013.png]: https://img-blog.csdnimg.cn/2018110810383013.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NzU4NDk3_size_16_color_FFFFFF_t_70 2]: https://img-blog.csdnimg.cn/20181108104006261.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NzU4NDk3,size_16,color_FFFFFF,t_70
[20181108104037905.png]: https://img-blog.csdnimg.cn/20181108104037905.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NzU4NDk3_size_16_color_FFFFFF_t_70 3]: https://img-blog.csdnimg.cn/20181108104112385.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NzU4NDk3,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NzU4NDk3_size_16_color_FFFFFF_t_70 4]: https://img-blog.csdnimg.cn/20181108104414831.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NzU4NDk3,size_16,color_FFFFFF,t_70
[20181108104211408.png]: https://img-blog.csdnimg.cn/20181108104211408.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NzU4NDk3_size_16_color_FFFFFF_t_70 5]: https://img-blog.csdnimg.cn/20181108104237786.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NzU4NDk3,size_16,color_FFFFFF,t_70